X-Git-Url: http://git.indexdata.com/?p=mkws-moved-to-github.git;a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=d33dc7cd3bdd1e4509548a95f411a6534ce04848;hp=a315a22979efea4a1fbb910b09bea0923bf2b5ef;hb=8dad748a1cedb9609bc898ec9d5cbb8dbcafe70d;hpb=fda7da00419e8b5fdd051505c1073affa9690ae2

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index a315a22..d33dc7c 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -1,6 +1,6 @@
 % The MKWS manual: embedded metasearching with the MasterKey Widget Set
 % Mike Taylor
-% October 2014
+% November 2014
 
 
 Introduction
@@ -41,7 +41,7 @@ flexibility against convenience:
   [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
@@ -150,7 +150,8 @@ To see all of these working together, just put them all into the HTML
 	<div class="mkws-stat"></div>
 
 The full set of supported widgets is described in the
-reference guide below.
+reference guide
+[below](#widgets).
 
 Widget team
 -----------
@@ -170,22 +171,6 @@ is part of the `aux` team.
 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
 ===================
 
@@ -201,18 +186,16 @@ like this:
 	    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 items is described in the
+The full set of supported configuration settings is described in the
 reference guide below.
 
 Per-widget configuration
@@ -220,7 +203,7 @@ 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:
 
@@ -237,11 +220,11 @@ attributes prefixed with `data-mkws-`, so:
 
 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
@@ -266,7 +249,7 @@ etc., customised layouts may wish to treat each of these components
 separately. In this case, `mkws-results` can be omitted, and the
 following lower-level widgets provided instead:
 
-* `mkws-termlists` -- provides the facets
+* `mkws-facets` -- provides the facets
 
 * `mkws-ranking` -- provides the options for how records are sorted and
    how many are included on each page of results.
@@ -559,37 +542,43 @@ its own User Access record.
 
 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
+Proxy when establishing the session. This is done
+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" };
 
 ### (Optional): conceal credentials from HTML source
 
-Using a credential-based Service-Proxy authentication URL such as the
-one above reveals the the credentials to public view -- to anyone who
-does View Source on the MKWS application. This may be acceptable for
-some libraries, but is intolerable for those which provide
-authenticated access to subscription resources.
-
-In these circumstances, a more elaborate approach is necessary. The
-idea is to make a URL local to the customer that is used for
-authentication onto the Service Proxy, hiding the credentials in a
-local rewrite rule. Then local mechanisms can be used to limit access
-to that local authentication URL. Here is one way to do it when
+Using credential-based authentication settings such as those above
+reveals the the credentials to public view -- to anyone who does View
+Source on the MKWS application. This may be acceptable for some
+libraries, but is intolerable for those which provide authenticated
+access to subscription resources.
+
+In these circumstances, a different approach is
+necessary. Referer-based or IP-based authentication may be
+appropriate. But if these are not possible, then a more elaborate
+approach can be used to hide the credentials in a web-server
+configuration that is not visible to users.
+
+The idea is to make a Service Proxy authentication URL local to the
+customer, hiding the credentials in a rewrite rule in the local
+web-server's configuration. Then local mechanisms can be used to limit
+access to that local authentication URL. Here is one way to do it when
 Apache2 is the application's web-server, which we will call
-yourname.com:
+yourname.com`:
 
 Step 1: add a rewriting authentication alias to the configuration:
 
 	RewriteEngine on
-	RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
+	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
-<http://yourname.com/spauth/>
+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/>
+Step 3: protect access to the local path `http://yourname.com/spauth/`
 (e.g. using a `.htaccess` file).
 
 
@@ -632,102 +621,469 @@ attribute as follows:
 Reference guide
 ===============
 
-Configuration object
---------------------
+Widgets
+-------
 
-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.
+The following widgets are provided in the core set. (Others can be
+added: see the [MKWS developers' guide](mkws-developer.html).)
 
 ----
-Element                   Type    Default   Description
---------                  -----   --------- ------------
-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.
-
-facets                    array   *Note 1*  Ordered list of names of facets to display. Supported facet names are
-                                            `xtargets`, `subject` and `author`.
+Name              Description
+----              -----------
+`auth-name`       Initially empty, it updates itself to shows the name
+                  of the library that the application is logged in as
+                  when authentication is complete.
+
+`builder`         A button which, when pressed, analyses the current
+                  settings of the team that it is a part of, and
+                  generates the HTML for an auto-searching element
+                  that will replicate the present search. This HTML is
+                  displayed in an alert box: it is intended that this
+                  widget be subclassed to store the generated widget
+                  definitions in more useful places.
+
+`button`          The search button. Usually generated a `search`
+                  widget.
+
+`categories`      Obtains from the Service Proxy a list of the target
+                  categories associated with the library in use, and
+                  displays them in a drop-down list. When a category
+                  is selected, searches are limited to the targets
+                  that are part of that category.
+
+`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 settings at the team
+                  level.
+
+`console-builder` Like the `builder` widget, but emits the generated
+                  HTML on the JavaScript console. This exists to
+                  provide an example of how to subclass the `builder`
+                  widget.
+
+`cover-art`       Displays cover art for a book by searching in
+                  Amazon. Often used with an `autosearch` attribute to
+                  indicate what book to display. For example,
+                  `<div class="mkws-cover-art" autosearch="isbn=1291177124"></div>`
+                  displays cover art for _All Yesterdays: Unique and
+                  Speculative Views of Dinosaurs and Other Prehistoric
+                  Animals_.
+                  For this widget to work, a library that includes the
+                  AmazonBooks target must be used. For example, the
+                  "DEMO AmazonBooks for MKWS" account, which can be
+                  selected with `sp_auth_credentials="mkws-amazon/mkws"`.
+
+`details`         This widget is generated by the toolkit itself to
+                  hold the full details of records that are initially
+                  listed in summary form.
+
+`done`            Initially empty, this widget is set to display
+                  "Search complete: found _n_ records" when all
+                  targets have completed their work, either returning
+                  a hit-count or an error. The message displayed can
+                  be changed by overriding the `done` template using
+                  `<script class="mkws-template-done" type="text/x-handlebars-template">`.
+
+`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 setting, which
+                  may conveniently be done by means of the
+                  `data-mkws-facet` attribute on the HTML
+                  element. The supported facets are "subject",
+                  "author" and "xtargets" -- the latter a special case
+                  which treats the target providing a record as a
+                  facet. Most often, `facet` widgets are generated
+                  by a `facets` widget, which knows which facets are
+                  required, but they can also be placed individually.
+
+`facets`          An area that contains a "Facets" heading and several
+                  `facet` widgets. The set of facet widgets generated
+                  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
+                  setting is an array of zero or more strings, each
+                  naming a facet.
+
+`google-image`    A specialisation of the `images` widget which
+                  defaults to the `Google_Images` target.
+
+`images`          A specialisation of the `records` widget which
+                  defaults to the `images` template. Unlike the default
+                  summary template, this displays an image from the
+                  URL specified by the `md-thumburl` field of each
+                  record.
+
+`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 setting, whose value is an array of
+                  two-letter language codes).
+
+`log`             Initially empty, this widget accumulates a log of
+                  messages generated by the widget set, similar to
+                  those emitted on the JavaScript console.
+
+`lolcat`          A specialisation of the `google-image` widget which
+                  defaults to the search-term "kitteh" and
+                  auto-executes.
+
+`motd-container`  An empty container which the `motd` widget, if any,
+                  is moved into for initial display. Usually generated
+                  as part of the `results` widget.
+
+`motd`            May be provided, containing content to appear in the
+                  area where records will later appear. It is moved
+                  into this area (the `motd-container` widget) and
+                  initially displayed; then hidden when the first
+                  search is run. It can be used to provide a "message
+                  of the day".
+
+`navi`            Shows a list of the facets that have been selected,
+                  and allows them to be deselected.
+
+`pager`           Shows a list of the available pages of results, and
+                  allows the user to navigate to a selected page.
+
+`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 specified as the
+                  `perpage_options` configuration setting, whose value is
+                  an array of integers. The initial selected value can
+                  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.
+
+`query`           The input area for a query. Usually generated a `search`
+                  widget.
+
+`ranking`         The result-ranking area, consisting of a `sort`
+                  widget and a `per-page` widget. These may instead
+                  be specified separately if preferred.
+
+`record`          A detailed display of a single record, usually
+                  appearing when the user clicks on a summary
+                  record. This is generated by the `records` widget.
+
+`records`         The area in which summary records appear. (Clicking
+                  on a summary record make it pop up as a detailed
+                  record.)
+
+`reference`       A short summary about a subject specified by the
+                  `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
+                  `wikimedia_wikipedia_single_result` target.
+
+`results`         A large compound widget used to provide the most
+                  important results-oriented widgets in a pre-packaged
+                  framework: `facets`, `ranking`, `pager`, `navi` and
+                  `records`.
+
+`search-form`     The search form, containing the query area and the
+                  button. Usually generated a `search` widget.
+
+`search`          The search box, consisting of a form containing a
+                  query area and a button.
+
+`sort`            Provides a dropdown allowing the user to choose how
+                  the displayed records should be sorted. The
+                  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 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
+                  many of them have been retrieved for display. For
+                  most purposes, the `progress` widget may be
+                  preferable.
+
+`summary`         A short record, included in the list shown when a
+                  search is run. When clicked, this generally pops up
+                  a detailed `record` widget. This widget is generated
+                  by the toolkit in response to search results.
+
+`switch`          A pair of buttons allowing the user to switch
+                  between viewing the search results (the usual case)
+                  or the target list.
+
+`targets`         A list of all targets in the present library,
+                  showing their ID, the number of records they have
+                  found for the current search, any diagnostics they
+                  have returned, the number of records that have been
+                  returned for display, and the connection state.
+----
 
-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.
+Configuration settings
+----------------------
 
-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.
+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.
 
-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.
+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.
 
-perpage_default           string  20        The initial value for the number of records to show on each page.
+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.
 
-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.
+----
+Setting                   Widget    Type    Default   Description
+--------                  ------    -----   --------- ------------
+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     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     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     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.
+
+lang                      _team_    string            The 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.
+
+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.
+
+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_  string  info      The lowest level of logging output to emit. Acceptable values are
+                                                      `trace`, `debug`, `info`, `warn`, `error` and `fatal`.
+
+maxrecs                   facet,    int               Limits the metasearching middleware to retrieving no more than the specified
+                          facets,                     number of records from each target.
+                          record,
+                          records,
+                          results
+
+newsearch_opacity         records,  float             If defined, a fractional value between in the range 0.0 (transparent) to 1.0
+                          facets                      (opaque). When a new search is submitted, the widget fades to that opacity
+                                                      (reverting to full opacity when data arrives).
+
+paragraphs                reference int               Limits the number of paragraphs rendered to the specified number. If
+                                                      omitted, there is no limit.
+
+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 the [Assembling Pazpar2
+                                                      URLs](#assembling-pazpar2-urls) section below.
+
+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,                     with which a user chooses the page-size in an interactive session.
+                          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 2*  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  *Note 3*  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_  string  *Note 4*  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.
+
+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.
+
+sentences                 reference int               Limits the number of sentences rendered to the specified number. If
+                                                      omitted, there is no limit.
+
+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 `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.
+
+service_proxy_auth_domain _global_  domain            When the server used for authentication -- e.g. the one identified by the
+                                                      `service_proxy_auth` URL -- proxies for different server, this can be set to
+                                                      the domain of the server that it proxies for, so that cookies are rewritten
+                                                      to appear to be from this domain.
+
+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.
+
+sort                      facet,    string            Specifies the order in which to sort the records retrieved by an
+                          facets,                     auto-executing widget. Must be one of those in the `sort_options`
+                          record,                     array. Contrast with `sort_default`, which is used to prime the dropdown
+                          records,                    with which a user chooses the sortorder in an interactive session.
+                          results
+
+sort_default              _team_    string  relevance The default sort criterion to use. Must be one of those in the
+                                                      `sort_options` array.
+
+sort_options              ranking   array   *Note 5*  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       _global_  string            If defined, this must be a slash-separated combination of username and
+                                                      password, which is sent as the authentication credentials on session
+                                                      initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
+                                                      section below.
+
+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 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
+                          facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
+                          record,                     section above.
+                          records,
+                          results
+
+targetfilter              facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
+                          facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
+                          record,                     section above.
+                          records,
+                          results
+
+targets                   facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
+                          facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
+                          record,                     section above.
+                          records,
+                          results
+
+template                  details,  string            Numerous widgets use Handlebars templates to render HTML. In general, each
+                          done,                       of these by default uses a template with the same name as the widget
+                          facet,                      itself. Individual widgets can be customised to use a template of a
+                          facets,                     different name by means of their `template` setting. The `records` widget
+                          images,                     (and `record`, an equivalent that shows only a single record) use the
+                          lang,                       `summary` template as well as the `records` template.
+                          navi,
+                          pager,
+                          progress,
+                          ranking,
+                          records,
+                          reference,
+                          results,
+                          search,
+                          stat,
+                          switch,
+                          targets
+
+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
+                                                      than raw Pazpar2. An authentication phase is run during initialisation.
+----
 
-query_width               int     50        The width of the query box, in characters.
+The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
+widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
+customise the display than by providing a full HTML structure.
 
-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.
+### Notes
 
-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.
+1. The default for `facets` is `["xtargets", "subject", "author"]`
 
-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`.
+2. The default for `perpage_options` is `[10, 20, 30, 50]`
 
-show_lang                 bool    true      Indicates whether or not to display the language menu.
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
 
-show_perpage              bool    true      Indicates whether or not to display the perpage menu.
+4. The default for `pp2_path` is `"service-proxy/"`
 
-show_sort                 bool    true      Indicates whether or not to display the sort menu.
+5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
 
-show_switch               bool    true      Indicates whether or not to display the switch menu, for switching between showing
-                                            retrieved records and target information.
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
 
-sort_default              string  relevance The label of the default sort criterion to use. Must be one of those in the `sort`
-                                            array.
+### Indirect settings
 
-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`.
+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_.
 
-use_service_proxy         bool    true      If true, then a Service Proxy is used to deliver searching services rather than raw
-                                            Pazpar2.
-----
+The currently supported types are:
 
-Perhaps we should get rid of the `show_lang`, `show_perpage`,
-`show_sort` and `show_switch` configuration items, and simply 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.
+* `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`
 
-### Notes
+* `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`
 
-1. ["sources", "subjects", "authors"]
+* `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:
 
-2. /pazpar2/search.pz2
+<!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
 
-3. [10, 20, 30, 50]
+		<script>var _reversedParam = extractAndReverse("term");</script>
+		<div class="mkws-results" autosearch="!var!_reversedParam">
 
-4. http://sp-mkws.indexdata.com/service-proxy-auth
+### Assembling Pazpar2 URLs
 
-5. http://sp-mkws.indexdata.com/service-proxy/
+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.
 
-6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+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
 ----------------------
@@ -748,53 +1104,71 @@ in the specified language. For example:
 	}
 
 The following strings occurring in the UI can be translated:
-`Displaying`,
-`Next`,
-`Prev`,
-`Records`,
-`Search`,
-`Sort by`,
-`Targets`,
-`Termlists`,
-`and show`,
-`found`,
-`of`,
-`per page`
-and
-`to`.
+
+* `Search complete: found`
+* `records`
+* `Displaying`
+* `to`
+* `of`
+* `found`
+* `Prev`
+* `Next`
+* `Sort by`
+* `and show`
+* `per page`
+* `Search`
+* `Active clients`
+* `Retrieved records`
+* `Records`
+* `Targets`
+* `Target ID`
+* `Hits`
+* `Diags`
+* `Records`
+* `State`
 
 In addition, facet names can be translated:
-`Authors`,
-`Sources`
-and
-`Subjects`.
+
+* `Authors`
+* `Sources`
+* `Subjects`
+
+and whatever field captions are defined by `facet_caption_*` settings.
+
+And sort-orders:
+
+* `relevance`
+* `title`
+* `newest`
+* `oldest`
+
+and whatever sort-orders are defined by the `sort_options` setting.
 
 Finally, the names of fields in the full-record display can be
 translated. These include, but may not be limited to:
-`Author`,
-`Date`,
-`Location`,
-`Subject`
-and
-`Title`.
-
 
+* `Title`
+* `Date`
+* `Author`
+* `Links`
+* `Subject`
+* `Locations`
 
 jQuery UI popup invocation
 --------------------------
 
 The MasterKey Widget Set can be invoked in a popup window on top of the page.
 
-Note that when using the `popup` layout, facilities from the jQuery UI
-toolkit are used, so it's necessary to include both CSS and JavaScript
-from that toolkit. The relevant lines are:
+Note that the `popup` widget uses facilities from the jQuery UI, so
+it's necessary to include both CSS and JavaScript from that
+toolkit. The relevant lines are:
 
 	<script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
 	<link rel="stylesheet" type="text/css"
 	      href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
 
 	<div class="mkws-search"></div>
-	<div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
+	<div class="mkws-popup" popup_width="1024" popup_height="650" popup_autoOpen="0">
 	  <div class="mkws-switch"></div>
 	  <div class="mkws-lang"></div>
 	  <div class="mkws-results"></div>
@@ -802,96 +1176,127 @@ from that toolkit. The relevant lines are:
 	  <div class="mkws-stat"></div>
 	</div>
 
+Popup windows can contain any HTML, not just MKWS widgets.
+
+The properties of the `popup` widget are as follows:
+
 ----
-Element         Type    Default             Description
+Setting         Type    Default             Description
 --------        -----   -------             ------------
-popup_width     string  880                 Width of the popup window (if used), in
-                                            pixels.
+popup_width     int     880                 Width of the popup window, in pixels.
 
-popup_height    string  760                 Height of the popup window (if used), in
-                                            pixels.
+popup_height    int     760                 Height of the popup window, in pixels.
 
-popup_button    string  `input.mkwsButton`  A click on this selector will trigger the
-					    popup to open
+popup_button    string  `input.mkwsButton`  A jQuery selector identifying the element which, which clicked, pops up the window.
 
-popup_modal     string  0                   Modal confirmation mode. Valid values are 0 or 1
+popup_modal     bool    0                   Indicates whether the popup is modal (blocks access to the background page until
+                                            dismissed). Set to 1 if a modal popup is required.
 
-popup_autoOpen  string  1                   Open popup window on load. Valid values are 0 or 1
+popup_autoOpen  bool    1                   Indictaes whether to pop up the window automatically when the page is loaded.
 
 ----
 
-You can have more than one mkws-popup widgets on a page. Please use a different 
-popup_button value to address the right ones.
+Multiple `popup` widgets can co-exist on a page. In this case, different
+`popup_button` values must be used for each.
 
-The structure of the HTML generated by the MKWS widgets
--------------------------------------------------------
+Structure of HTML generated by widgets
+--------------------------------------
 
 In order to override the default CSS styles provided by the MasterKey Widget
-Set, it's necessary to understand that structure of the HTML elements that are
-generated within the widgets. This knowledge make it possible, for example,
-to style each `<div>` with class `term` but only when it occurs inside an
-element with class `mkws-termlists`, so as to avoid inadvertently styling other
-elements using the same class in the non-MKWS parts of the page.
-
-The HTML structure is as follows. As in CSS, #ID indicates a unique identifier
-and .CLASS indicates an instance of a class.
-
-	#mkwsSwitch
-	  a*
-	
-	#mkwsLang
-	  ( a | span )*
+Set, it's necessary to understand the structure of the HTML elements that are
+generated within the widgets. The HTML structure is as follows. As in CSS,
+_.class_ indicates an instance of a class. A trailing `*` indicates zero or
+more instances; a trailing `?` indicates zero or one instance.
+
+	.mkws-progress
+	  span.mkws-done
+	  span.mkws-waiting
 	
-	#mkwsSearch
-	  form
-	    input#mkwsQuery type=text
-	    input#mkwsButton type=submit
+	.mkws-search
+	  form.mkws-search-form
+	    input.mkws-query
+	    input.mkws-button
 	
-	#mkwsBlanket
-	  (no contents -- used only for masking)
-	
-	#mkwsResults
+	.mkws-results
 	  table
 	    tbody
 	      tr
-	        td
-	          #mkwsTermlists
-	            div.title
-	            div.facet*
-	              div.termtitle
-	              ( a span br )*
-	        td
-	          div#mkwsRanking
-	            form#mkwsSelect
-	              select#mkwsSort
-	              select#mkwsPerpage
-	          #mkwsPager
-	          #mkwsNavi
-	          #mkwsRecords
-	            div.record*
-	              span (for sequence number)
-	              a (for title)
-	              span (for other information such as author)
-	              div.details (sometimes)
+	        td.mkws-facets-container-wide
+	          div.mkws-facets
+	            div.mkws-facet*
+	              div.mkws-facet-title
+	              div.mkws-term*
+	                a
+	                span
+	        td.mkws-motd-container
+	          div.mkws-ranking
+	            form
+	              select.mkws-sort
+	                option*
+	              select.mkws-perpage
+	                option*
+	          div.mkws-pager
+	            div
+	            div
+	              span.mkws-prev
+	              span.mkws-current-page
+	              a*
+	              span.mkws-next
+	          div.mkws-navi
+	          div.mkws-records
+	            div.mkws-summary*
+	              div.mkws-field-data
+	                span.mkws-field-NAME*
+	              div.mkws-details?
 	                table
 	                  tbody
 	                    tr*
 	                      th
 	                      td
-	#mkwsTargets
-	  #mkwsBytarget
-	    table
-	      thead
-	        tr*
-	          td*
-	      tbody
-	        tr*
-	          td*
+	      tr
+	        td
+	          div.mkws-facets-container-narrow
+	
+	.mkws-targets
+	  table
+	    thead
+	      tr
+	        td*
+	    tbody
+	      tr*
+	        td*
 	
-	#mkwsStat
-	  span.head
-	  span.clients
-	  span.records
+
+Appendix: compatibility roadmap
+===============================
+
+Wherever possible, we ensure that all functional changes in MKWS are
+backwards-compatible, so that applications written against old versions of the
+toolkit will continue to work when running against newer versions.
+
+However, a few aspects of functionality unavoidably change in backwards
+incompatible ways. We ensure that **this only happens with new major
+versions** -- so it should _always_ be safe to upgrade to a new minor version.
+As an aid to porting old applications, we here note the specific
+backwards-incompatible changes in the various major releases, and those
+planned for future major releases.
+
+
+Major version 1.x
+-----------------
+
+Versions of MKWS before v1.0 (including the only prior release, v0.9.1) 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.
+
 
 - - -