X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=f05b06912d9c8027020d78e57af201a8581d8761;hb=ca89ae22902fc3f25119b59880e383d88ccaffab;hp=55c5f67ab9d9572d611bb7180e973b246f89cd44;hpb=34bb5bebdbd3f5e02afde725c653201ba1c2655f;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 55c5f67..f05b069 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -860,26 +860,37 @@ default values are in footnotes to keep the table reasonably narrow. ---- Element Widget Type Default Description -------- ------ ----- --------- ------------ -auth_hostname _global_ +auth_hostname _global_ string If provided, overrides the `pp2_hostname` setting when constructing the + Service Proxy authentication URL. This need only be used when authentication + is performed on a different host from the remaining operations (search, + retrieve, etc.) -autosearch facet, - facets, +autosearch facet, string If provided, this setting contains a query which is immediately run on behalf + facets, of the team. Often used with an [indirect setting](#indirect-settings). record, records, results -facet facet +facet facet string For a `facet` widget, this setting is mandatory, and indicates which field to + list terms for. Three fields are supported: `subject`, `author` and + `xtargets` -- the latter a special case which treats the target providing a + record as a facet. Any other field may also be used, but the default caption + and maximum term-count may not be appropriate, needing to be overridden by + `facet_caption_*` and `facet_max_*` settings. -facet_caption_* facet +facet_caption_* facet string Specifies what on-screen caption is to be used for the named facet: for + example, if a `date` facet is generated, then `facet_caption_date` can be + used to set the caption to "Year". -facet_max_* facet +facet_max_* facet int Specifies how many terms are to be displayed for the named facet: for + example, if a `publisher` facet is generated, then `facet_max_publisher` can + be used to limit the list to the top six. -facets _team_ array *Note 1* Ordered list of names of facets to display. Supported facet names are - `xtargets`, `subject` and `author`. +facets _team_ array *Note 1* Ordered list of names of facets to display. -lang _team_ string en Code of the default language to display the UI in. Supported language codes - are `en` = English, `de` = German, `da` = Danish, and whatever additional - languages are configured using `language_*` entries (see below). +lang _team_ string Two-letter ISO code of the default language to display the UI in. Supported + language codes are `en` = English, `de` = German, `da` = Danish, and whatever + additional languages are configured using `language_*` entries (see below). lang_options lang array [] A list of the languages to offer as options. If empty (the default), then all configured languages are listed. @@ -888,32 +899,32 @@ language_* _global_ hash Support for any number of name is `language_` followed by the code of the language. See the separate section below for details. -limit facet, - facets, - record, - records, - results +limit facet, string Allows a partial search to be included in the specification of an + facets, auto-executing widget. This is ANDed with the submitted query, as though it + record, had been selected from a facet. See the Search section in [the Protocol + records, chapter of the Pazpar2 manual + results ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html) log_level _global_ int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with datestamps, 3 = messages with datestamps and stack-traces. -maxrecs facet, - facets, +maxrecs facet, int Limits the metasearching middleware to retrieving no more than the specified + facets, number of records from each target. record, records, results -paragraphs reference +paragraphs reference int Limits the number of paragraphs rendered to the specified number. -pazpar2_url _global_ string *Note 2* The URL used to access the metasearch middleware. This service must be - configured to provide search results, facets, etc. It may be either - unmediated or Pazpar2 the MasterKey Service Proxy, which mediates access to - an underlying Pazpar2 instance. In the latter case, `service_proxy_auth` must - be provided. +pazpar2_url _global_ string If specified, this is the URL used to access the metasearch middleware. This + service must be configured to provide search results, facets, etc. It may be + either unmediated Pazpar2 or the MasterKey Service Proxy, which mediates + access to an underlying Pazpar2 instance. When not specified, the URL is + assembled from `pp2_hostname` and `pp2_path`. See *Note 2* -perpage facet, - facets, - record, +perpage facet, int Specifies the number of records to show per page in an auto-executing + facets, widget. Contrast with `perpage_default`, which is used to prime the dropdown + record, which which a user chooses the page-size in an interactive session. records, results @@ -922,9 +933,15 @@ perpage_default _team_ string 20 The initial value for the perpage_options ranking array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many records are displayed on each page of results. -pp2_hostname _global_ +pp2_hostname _global_ string *Note 7* Unless overridden by the `pazpar2_url` setting, this is used together with + `pp2_path` to construct the URL to the Pazpar2 service (or Service + Proxy). Set this to connect to a service on a different host from the + default. -pp2_path _global_ +pp2_path _global_ string *Note 8* Unless overridden by the `pazpar2_url` setting, this is used together with + `pp2_hostname` to construct the URL to the Pazpar2 service (or Service + Proxy). Set this to connect to a service on a different host from the + default. query_width _search_ int 50 The width of the query box, in characters. @@ -933,13 +950,16 @@ responsive_design_width _global_ int If defined, then the facet threshhold width, in pixels, at which the facets move between their two locations. -scan_all_nodes _global_ +scan_all_nodes _global_ bool -sentences reference +sentences reference int Limits the number of paragraphs rendered to the specified number. -service_proxy_auth _global_ url *Note 4* A URL which, when `use_service_proxy` is true, is fetched once at the - beginning of each session to authenticate the user and establish a session - that encompasses a defined set of targets to search in. +service_proxy_auth _global_ url If defined, this is the URL which, when `use_service_proxy` is true, is + fetched once at the beginning of each session to authenticate the user and + establish a session that encompasses a defined set of targets to search + in. When not defined, the URL is assembled from `auth_hostname` or + `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and + `sp_auth_credentials`. See *Note 4* for details. service_proxy_auth_domain _global_ domain Can be set to the domain for which `service_proxy_auth` proxies authentication, so that cookies are rewritten to appear to be from this @@ -955,7 +975,7 @@ show_sort ranking bool true Indicates whether or not t show_switch switch bool true Indicates whether or not to display the switch menu, for switching between showing retrieved records and target information. -sort facet, +sort facet, string facets, record, records, @@ -969,31 +989,31 @@ sort_options ranking array *Note 6* List of supported sort cri sort-expression such as `data:0` and the second is a human-readable label such as `newest`. -sp_auth_credentials _global_ +sp_auth_credentials _global_ string -sp_auth_path _global_ +sp_auth_path _global_ string *Note 9* -sp_auth_query _global_ +sp_auth_query _global_ string *Note 10* -target facet, +target facet, string facets, record, records, results -targetfilter facet, +targetfilter facet, string facets, record, records, results -targets facet, +targets facet, string facets, record, records, results -template details, +template details, string done, facet, facets, @@ -1012,33 +1032,45 @@ template details, switch, targets -text builder +text builder string use_service_proxy _global_ bool true If true, then a Service Proxy is used to deliver searching services rather than raw Pazpar2. ---- -Perhaps we should get rid of the `show_lang`, `show_perpage`, +(Perhaps we should get rid of the `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings, as we display the relevant menus only when their containers are provided -- e.g. an `mkws-lang` element for the language menu. But for now we retain these, as an easier route to lightly customise the display than by providing a full HTML -structure. +structure.) ### Notes -1. ["sources", "subjects", "authors"] +1. ["xtargets", "subject", "author"] -2. /pazpar2/search.pz2 +2. ### describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`. 3. [10, 20, 30, 50] -4. http://sp-mkws.indexdata.com/service-proxy-auth +4. ### describe how `service_proxy_auth` is assembled from `auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and +`sp_auth_credentials`. -5. http://sp-mkws.indexdata.com/service-proxy/ +5. "http://sp-mkws.indexdata.com/service-proxy/" 6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]] +7. "sp-mkws.indexdata.com" + +8. "service-proxy" + +9. The default for `sp_auth_path` is `"service-proxy/"`. + +10. The default for `sp_auth_query` is `"command=auth&action=perconfig"`. + +### Indirect settings + +FIXME !query!q, !path!2, etc. Language specification ----------------------