----
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.)
-
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,
Proxy). Set this to connect to a service on a different host from the
default.
-responsive_design_width _global_ int If defined, then the facets display moves between two locations as the
- screen-width varies. The specified number is the threshhold width, in
- pixels, at which the facets move between their two locations. The `switch`
- and `lang` widgets also disappear entirely below this threshhold.
-
scan_all_nodes _global_ bool false An internal setting that changes how MKWS scans the HTML documen to discover
widgets. If set to true, a different approach is used which may be faster
under some circumstances.
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
+ in. When not defined, the URL is assembled from `sp_auth_hostname` or
+ `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and
`sp_auth_credentials`. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
section below.
-sp_auth_path _global_ string *Note 6* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_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.)
+
+sp_auth_path _global_ string Part of the URL used for authentication. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
-sp_auth_query _global_ string *Note 7* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_query _global_ string *Note 6* Part of the URL used for authentication. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
target facet, string One of three ways to select which targets an auto-searching widgets uses. See
switch,
targets
-<!--- The widget called "record" is a special-case of "records"; both also use "summary" -->
-
text builder string "Build!" Specifies what text to use for the Builder button.
use_service_proxy _global_ bool true If true, then a Service Proxy is used to deliver searching services rather
3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
-4. The default for `pp2_path` is `"service-proxy"`
+4. The default for `pp2_path` is `"service-proxy/"`
5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
-6. The default for `sp_auth_path` is `"service-proxy/"`.
-
-7. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
### Indirect settings
The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
-example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch query. FIXME
-say more.
+example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
+query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
+
+The currently supported types are:
+
+* `param` -- uses the value of the specified query parameter for the URL. For example
+`<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
+invoked from the URL `http://example.com/magic/example.html?term=sushi`
+
+* `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
+`!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
+invoked from the URL `http://example.com/magic/lookup/dinosaur`
-FIXME !query!q, !path!2, etc.
+* `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
+ search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
+ extraction and reversing, the use the HTML:
+
+<!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
+
+ <script>var _reversedParam = extractAndReverse("term");</script>
+ <div class="mkws-results" autosearch="!var!_reversedParam">
### Assembling Pazpar2 URLs
-FIXME describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`; and how `service_proxy_auth` is assembled from
-`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
+Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
+assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
+endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
+
+In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
+is generally made to the same endpoint as the other requests. However, the hostname used for authentication may if necessary be
+overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
+`sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
+
+So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
+(sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
+and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
+URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.
Language specification
----------------------