X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=864b56fc61704f0006123b91852145b68973c675;hb=ef234764b8959f8cf0d73ed1a3d950c847e01d2c;hp=0601a7990ba65c393c2685af055afa73f68f3ab9;hpb=a5ad301e7371aef956524a85e3567eb261ab70bc;p=mkws-moved-to-github.git

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 0601a79..864b56f 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -590,7 +590,8 @@ 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/`.
@@ -659,6 +660,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,131 +703,264 @@ Name              Description
                   be changed by overriding the `done` template using
                   `<script class="mkws-template-done" type="text/x-handlebars-template">`.
 
-`facet`           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.
 
-`facets`          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.
+----
 
-`google-image`    x
 
-`images`          x
+Configuration object
+--------------------
 
-`lang`            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.
 
-`log`             x
+----
+Element                   Widget  Type    Default   Description
+--------                  ------  -----   --------- ------------
+auth_hostname
 
-`lolcat`          x
+autosearch
 
-`motd-container`  x
+facet
 
-`motd`            x
+facet_caption_*
 
-`navi`            x
+facet_max_*
 
-`pager`           x
+facets                            array   *Note 1*  Ordered list of names of facets to display. Supported facet names are
+                                                    `xtargets`, `subject` and `author`.
 
-`per-page`        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).
 
-`progress`        x
+lang_options                      array   []        A list of the languages to offer as options. If empty (the default), then all
+                                                    configured languages are listed.
 
-`query`           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.
 
-`ranking`         x
+limit
 
-`record`          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.
 
-`records`         x
+maxrecs
 
-`reference`       x
+paragraphs
 
-`results`         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-form`     x
+perpage
 
-`search`          x
+perpage_default                   string  20        The initial value for the number of records to show on each page.
 
-`sort`            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.
 
-`stat`            x
+pp2_hostname
 
-`switch`          x
+pp2_path
 
-`targets`         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`,
@@ -913,7 +1050,7 @@ from that toolkit. The relevant lines are:
 	      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>