From: Mike Taylor <mike@indexdata.com>
Date: Tue, 4 Nov 2014 15:27:23 +0000 (+0000)
Subject: Merge branch 'master' of ssh://git.indexdata.com/home/git/pub/mkws
X-Git-Tag: 1.0.0~83^2~5^2
X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=commitdiff_plain;h=7b8f519897c9b6ac4da2b83080ecd0fb6127b802;hp=46e072ebe19e86e9b56203790aad6a765cc179c6;p=mkws-moved-to-github.git

Merge branch 'master' of ssh://git.indexdata.com/home/git/pub/mkws
---

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 0601a79..9abebd5 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -659,6 +659,9 @@ Name              Description
                   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
@@ -699,55 +702,141 @@ Name              Description
                   be changed by overriding the `done` template using
                   `<script class="mkws-template-done" type="text/x-handlebars-template">`.
 
-`facet`           x
-
-`facets`          x
-
-`google-image`    x
-
-`images`          x
-
-`lang`            x
-
-`log`             x
-
-`lolcat`          x
-
-`motd-container`  x
-
-`motd`            x
-
-`navi`            x
-
-`pager`           x
-
-`per-page`        x
-
-`progress`        x
-
-`query`           x
-
-`ranking`         x
-
-`record`          x
-
-`records`         x
-
-`reference`       x
-
-`results`         x
-
-`search-form`     x
-
-`search`          x
-
-`sort`            x
-
-`stat`            x
-
-`switch`          x
+`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
+                  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 item,
+                  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
+                  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 item, 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 set as the
+                  `perpage_options` configuration item, whose value is
+                  an array of integers. The initial selected value can
+                  be set by the `perpage_default` configuration item.
+
+`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.
 
-`targets`         x
+`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 item. 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 set as the
+                  `sort_options` configuration item, 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.
+
+`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.
 ----