relevance (though as always this can be changed in the UI) and makes
the search box a bit wider than the default.
-The full set of supported configuration items is described in the
+The full set of supported configuration settings is described in the
reference guide below.
Per-widget configuration
In addition to the global configuration provided by the `mkws_config`
object, individual widgets' behaviour can be configured by providing
-configuration items as attributed on their HTML elements. For example,
+configuration settings as attributes on their HTML elements. For example,
a `records` widget might be restricted to displaying no more than
three records by setting the `numrecs` parameter as follows:
For first form is more convenient; the second is more correct.
-Because some configuration items take structured values rather than
+Because some configuration settings take structured values rather than
simple strings, they cannot be directly provided by inline
attributes. To allow for this, the special attribute
`data-mkws-config`, if provided, is parsed as JSON and its key-value
-pairs set as configuration items for the widget in question. For
+pairs used as configuration settings for the widget in question. For
example, the value of `lang_options` is an array of strings specifying
which of the supported UI languages should be made available. The
following invocation will limit this list to only English and Danish
When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
Proxy when establishing the session. This is done
-by setting the `sp_auth_credentials` configuration item to a string
+by providing the `sp_auth_credentials` configuration setting as a string
containing the username and password separated by a slash:
mkws_config = { sp_auth_credentials: "mike/swordfish" };
RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/\
?command=auth&action=check,login&username=U&password=PW [P]
-Step 2: set the MKWS configuration item `service_proxy_auth` to
+Step 2: set the MKWS configuration setting `service_proxy_auth` to
`http://yourname.com/spauth/`.
Step 3: protect access to the local path `http://yourname.com/spauth/`
`config` This widget has no functionality of its own, but its
configuration is copied up into its team, allowing
it to affect other widgets in the team. This is the
- only way to set configuration items at the team
+ only way to set configuration settings at the team
level.
`console-builder` Like the `builder` widget, but emits the generated
`facet` A facet that displays the frequency with which a set
of terms occur within a specific field. The specific
field whose contents are analysed must be specified
- by the widget's `facet` configuration item, which
+ by the widget's `facet` configuration setting, which
may conveniently be done by means of the
`data-mkws-facet` attribute on the HTML
element. The supported facets are "subject",
`facets` An area that contains a "Facets" heading and several
`facet` widgets. The set of facet widgets generated
- is specified by the `facets` configuration item,
+ is specified by the `facets` configuration setting,
which may be set globally or at the level of the
widget or the team. The value of this configuration
- item is an array of zero or more strings, each
+ setting is an array of zero or more strings, each
naming a facet.
`google-image` A specialisation of the `images` widget which
`lang` Provides a selection between the supported set of
languages (which defaults to English, German and
Danish, but can be configured by the `lang`
- configuration item, whose value is an array of
+ configuration setting, whose value is an array of
two-letter language codes).
`log` Initially empty, this widget accumulates a log of
`per-page` Provides a dropdown allowing the user to choose how
many records should appear on each page. The
- available set of page-sizes can be set as the
- `perpage_options` configuration item, whose value is
+ available set of page-sizes can be specified as the
+ `perpage_options` configuration setting, whose value is
an array of integers. The initial selected value can
- be set by the `perpage_default` configuration item.
+ be specified by the `perpage_default` configuration setting.
`progress` Shows a progress bar which indicates how many of the
targets have responded to the search.
record.)
`reference` A short summary about a subject specified by the
- `autosearch` configuration item. This is created by
+ `autosearch` configuration setting. This is created by
drawing a picture and a paragraph of text from
Wikipedia. To work correctly, this widget must be
used in a library that provides the
`sort` Provides a dropdown allowing the user to choose how
the displayed records should be sorted. The
- available set of sort criteria can be set as the
- `sort_options` configuration item, whose value is
+ available set of sort criteria can be specified as the
+ `sort_options` configuration setting, whose value is
an array of two-element arrays. The first item of
each sub-array is a pazpar2 sort-expression such as
`data:0` and the second is a human-readable label
such as `newest`. The initial selected
- value can be set by the `sort_default` configuration
- item.
+ value can be specified by the `sort_default` configuration
+ setting.
`stat` A summary line stating how many targets remain
active, how many records have been found, and how
----
-Configuration object
---------------------
-
-The configuration object `mkws_config` may be created before including
-the MKWS JavaScript code to modify default behaviour. This structure
-is a key-value lookup table, whose entries are described in the table
-below. All entries are optional, but if specified must be given values
-of the specified type. If ommitted, each setting takes the indicated
-default value; long default values are in footnotes to keep the table
-reasonably narrow.
-
-----
-Element Widget Type Default Description
--------- ------ ----- --------- ------------
-auth_hostname
-
-autosearch
-
-facet
-
-facet_caption_*
-
-facet_max_*
-
-facets array *Note 1* Ordered list of names of facets to display. Supported facet names are
- `xtargets`, `subject` and `author`.
-
-lang 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_options array [] A list of the languages to offer as options. If empty (the default), then all
- configured languages are listed.
-
-language_* hash Support for any number of languages can be added by providing entries whose
- name is `language_` followed by the code of the language. See the separate
- section below for details.
-
-limit
-
-log_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
- datestamps, 3 = messages with datestamps and stack-traces.
-
-maxrecs
-
-paragraphs
-
-pazpar2_url 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.
-
-perpage
-
-perpage_default string 20 The initial value for the number of records to show on each page.
-
-perpage_options 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.
+Configuration settings
+----------------------
-pp2_hostname
+Configuration settings may be provided at the level of a indiviual widget, or a team, or globally. Per-widget configuration is
+described above; per-team settings can be placed in a `config` widget belonging to the relevant team, and will be applied to that
+team as a whole; and global settings are provided in the global variable `mkws_config`. This structure is a key-value lookup
+table, and may specify the values of many settings.
-pp2_path
+Some settings apply only to specific widgets; others to the behaviour of the tookit as a whole. When a widget does not itself have
+a value specified for a particular configuration setting, its team is consulted; and if that also does not have a value, the global
+settings are consulted. Only if this, too, is unspecified, is the default value used.
-query
+The supported configuration settings are described in the table below. For those settings that apply only to particular widgets,
+the relevant widgets are listed. All entries are optional, but if specified must be given values of the specified type. Long
+default values are in footnotes to keep the table reasonably narrow.
-query_width int 50 The width of the query box, in characters.
+----
+Element Widget Type Default Description
+-------- ------ ----- --------- ------------
+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.)
-responsive_design_width int If defined, then the facets display moves between two locations as the
- screen-width varies, as described above. The specified number is the threshhold
- width, in pixels, at which the facets move between their two locations.
+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
-scan_all_nodes
+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.
-sentences
+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".
-service_proxy_auth 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.
+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.
-service_proxy_auth_domain 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 domain. In general,
- this is not necessary, as this setting defaults to the domain of `pazpar2_url`.
+facets _team_ array *Note 1* Ordered list of names of facets to display.
-show_lang bool true Indicates whether or not to display the language menu.
+lang _team_ string en 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).
-show_perpage bool true Indicates whether or not to display the perpage menu.
+lang_options lang array [] A list of the languages to offer as options. If empty (the default), then all
+ configured languages are listed.
-show_sort bool true Indicates whether or not to display the sort menu.
+language_* _global_ hash Support for any number of languages can be added by providing entries whose
+ name is `language_` followed by the code of the language. See the separate
+ section below for details.
-show_switch bool true Indicates whether or not to display the switch menu, for switching between
- showing retrieved records and target information.
+limit facet, string ### See the Search section in
+ facets, [the Protocol chapter of the Pazpar2 manual
+ record, ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
+ records,
+ results
-sort
+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.
-sort_default string relevance The label of the default sort criterion to use. Must be one of those in the
- `sort` array.
+maxrecs facet, int
+ facets,
+ record,
+ records,
+ results
+
+paragraphs reference int
+
+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.
+
+perpage facet, int
+ facets,
+ record,
+ records,
+ results
+
+perpage_default _team_ string 20 The initial value for the number of records to show on each page.
+
+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_ string
+
+pp2_path _global_ string
+
+query_width _search_ int 50 The width of the query box, in characters.
+
+responsive_design_width _global_ int If defined, then the facets display moves between two locations as the
+ screen-width varies, as described above. The specified number is the
+ threshhold width, in pixels, at which the facets move between their two
+ locations.
+
+scan_all_nodes _global_ bool
+
+sentences reference int
+
+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_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
+ domain. In general, this is not necessary, as this setting defaults to the
+ domain of `pazpar2_url`.
+
+show_lang lang bool true Indicates whether or not to display the language menu.
+
+show_perpage ranking bool true Indicates whether or not to display the perpage menu.
+
+show_sort ranking bool true Indicates whether or not to display the sort menu.
+
+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, string
+ facets,
+ record,
+ records,
+ results
+
+sort_default _team_ string relevance The label of the default sort criterion to use. Must be one of those in the
+ `sort` array.
-sort_options array *Note 6* List of supported sort criteria. Each element of the list is itself a
- two-element list: the first element of each sublist is a pazpar2
- sort-expression such as `data:0` and the second is a human-readable label such
- as `newest`.
+sort_options ranking array *Note 6* List of supported sort criteria. Each element of the list is itself a
+ two-element list: the first element of each sublist is a pazpar2
+ sort-expression such as `data:0` and the second is a human-readable label
+ such as `newest`.
-sp_auth_credentials
+sp_auth_credentials _global_ string
-sp_auth_path
+sp_auth_path _global_ string
-sp_auth_query
+sp_auth_query _global_ string
-target
+target facet, string
+ facets,
+ record,
+ records,
+ results
-targetfilter
+targetfilter facet, string
+ facets,
+ record,
+ records,
+ results
-targets
+targets facet, string
+ facets,
+ record,
+ records,
+ results
-template
+template details, string
+ done,
+ facet,
+ facets,
+ images,
+ lang,
+ navi,
+ pager,
+ progress,
+ ranking,
+ record,
+ records,
+ reference,
+ results,
+ search,
+ stat,
+ switch,
+ targets
-text
+text builder string
-use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than
- raw Pazpar2.
+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`,
-`show_sort` and `show_switch` configuration items, and simply display the relevant menus
+(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 my changing providing a full HTML
-structure.
+to lightly customise the display than by providing a full HTML
+structure.)
### Notes
6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+### Indirect settings
+
+FIXME !query!q, !path!2, etc.
Language specification
----------------------