[Drupal](https://www.drupal.org/)
sites.
-All of these approaches require programming to a greater or lesser
+All but the last of these approaches require programming to a greater or lesser
extent. Against this backdrop, we introduced
[MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
-- a set of simple, very high-level HTML+CSS+JavaScript
Widgets that do not have a team specified (as in the examples above)
are placed in the team called `AUTO`.
-Old and new-style class-names
------------------------------
-
-**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
-without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
-used to specify team names used an `mkwsTeam_` prefix (with an
-underscore). So instead of `mkws-team-foo`, it used to be
-`mkwsTeam_foo`.
-
-The 1.x series of MKWS releases recognise these old-style class-names
-as well as the canonical ones, as a facility for backwards
-compatibility. However, **these old class-names are deprecated, and
-support will be removed in v2.0**. Existing applications that use them
-should be upgraded to the new-style class names as soon as convenient.
-
Configuring widgets
===================
lang_options: [ "en", "da" ]
lang: "da",
sort_default: "title",
- query_width: 60
};
</script>
<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
This configuration restricts the set of available UI languages English
and Danish (omitting German), sets the default to Danish (rather than
-the English), initially sorts search results by title rather than
-relevance (though as always this can be changed in the UI) and makes
-the search box a bit wider than the default.
+the English), and initially sorts search results by title rather than
+relevance (though as always this can be changed in the UI).
The full set of supported configuration settings is described in the
reference guide below.
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.
-
-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.
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
+ `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_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
-FIXME !query!q, !path!2, etc.
+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. 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`
+
+* `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
+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,
+
+and how `service_proxy_auth` is assembled from
`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
Language specification
span.clients
span.records
+
+Appendix: compatibility roadmap
+===============================
+
+FIXME: more to write here.
+
+
+Old and new-style class-names
+-----------------------------
+
+**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
+without hyphens and with second and subsequent words capitalised. So
+instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
+used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be
+`mkwsTeam_foo`.
+
+The 1.x series of MKWS releases recognise these old-style class-names
+as well as the canonical ones, as a facility for backwards
+compatibility. However, **these old class-names are deprecated, and
+support will be removed in v2.0**. Existing applications that use them
+should be upgraded to the new-style class names as soon as convenient.
+
+
- - -
Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>