X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=e4b81d118c67c25e568c604107d1031d69356339;hb=dfef0d6f251444f898064a1608832f24235c36f9;hp=5e7b617ec030a52a2a7c6d5edbea93a303c227c4;hpb=0ec7faad75a434d3605553285c8bdd1521fd1d78;p=mkws-moved-to-github.git

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 5e7b617..e4b81d1 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -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
 -----------
@@ -266,7 +267,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.
@@ -646,149 +647,318 @@ added: see the [MKWS developers' guide](mkws-developer.html).)
 ----
 Name              Description
 ----              -----------
-`auth-name`       x
-
-`builder`         x
-
-`button`          x
-
-`categories`      x
-
-`config`          x
-
-`console-builder` x
-
-`cover-art`       x
-
-`details`         x
-
-`done`            x
-
-`facet`           x
-
-`google-image`    x
+`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 items 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 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.
+
+`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.
+----
 
-`images`          x
 
-`lang`            x
+Configuration object
+--------------------
 
-`log`             x
+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.
 
-`lolcat`          x
+----
+Element                   Widget  Type    Default   Description
+--------                  ------  -----   --------- ------------
+auth_hostname
 
-`motd-container`  x
+autosearch
 
-`motd`            x
+facet
 
-`navi`            x
+facet_caption_*
 
-`pager`           x
+facet_max_*
 
-`per-page`        x
+facets                            array   *Note 1*  Ordered list of names of facets to display. Supported facet names are
+                                                    `xtargets`, `subject` and `author`.
 
-`progress`        x
+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).
 
-`query`           x
+lang_options                      array   []        A list of the languages to offer as options. If empty (the default), then all
+                                                    configured languages are listed.
 
-`ranking`         x
+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.
 
-`record`          x
+limit
 
-`records`         x
+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.
 
-`reference`       x
+maxrecs
 
-`results`         x
+paragraphs
 
-`search-form`     x
+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.
 
-`search`          x
+perpage
 
-`sort`            x
+perpage_default                   string  20        The initial value for the number of records to show on each page.
 
-`stat`            x
+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.
 
-`switch`          x
+pp2_hostname
 
-`targets`         x
+pp2_path
 
-`termlists`       x
-----
+query
 
+query_width                       int     50        The width of the query box, in characters.
 
-Configuration object
---------------------
+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.
 
-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.
+scan_all_nodes
 
-----
-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.
+sentences
 
-facets                    array   *Note 1*  Ordered list of names of facets to display. Supported facet names are
-                                            `xtargets`, `subject` and `author`.
+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.
 
-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).
+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`.
 
-lang_options              array   []        A list of the languages to offer as options. If empty (the default), then all
-                                            configured languages are listed.
+show_lang                         bool    true      Indicates whether or not to display the language menu.
 
-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.
+show_perpage                      bool    true      Indicates whether or not to display the perpage menu.
 
-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.
+show_sort                         bool    true      Indicates whether or not to display the sort menu.
 
-perpage_default           string  20        The initial value for the number of records to show on each page.
+show_switch                       bool    true      Indicates whether or not to display the switch menu, for switching between showing
+                                                    retrieved records and target information.
 
-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.
+sort
 
-query_width               int     50        The width of the query box, in characters.
+sort_default                      string  relevance The label of the default sort criterion to use. Must be one of those in the `sort`
+                                                    array.
 
-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.
+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`.
 
-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.
+sp_auth_credentials
 
-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`.
+sp_auth_path
 
-show_lang                 bool    true      Indicates whether or not to display the language menu.
+sp_auth_query
 
-show_perpage              bool    true      Indicates whether or not to display the perpage menu.
+target
 
-show_sort                 bool    true      Indicates whether or not to display the sort menu.
+targetfilter
 
-show_switch               bool    true      Indicates whether or not to display the switch menu, for switching between showing
-                                            retrieved records and target information.
+targets
 
-sort_default              string  relevance The label of the default sort criterion to use. Must be one of those in the `sort`
-                                            array.
+template
 
-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`.
+text
 
-use_service_proxy         bool    true      If true, then a Service Proxy is used to deliver searching services rather than raw
-                                            Pazpar2.
+use_service_proxy                 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`,
@@ -839,7 +1009,7 @@ The following strings occurring in the UI can be translated:
 `Search`,
 `Sort by`,
 `Targets`,
-`Termlists`,
+`Facets`,
 `and show`,
 `found`,
 `of`,
@@ -914,7 +1084,7 @@ 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
+element with class `mkws-facets`, 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