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.
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
be changed by overriding the `done` template using
`<script class="mkws-template-done" type="text/x-handlebars-template">`.
-`facet` 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
-
-`targets` 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.
-`termlists` 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.
----
`Search`,
`Sort by`,
`Targets`,
-`Termlists`,
+`Facets`,
`and show`,
`found`,
`of`,
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
projects / mkws-moved-to-github.git / blobdiff