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.
----
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
-
-`images` x
-
-`lang` x
-
-`log` x
-
-`lolcat` x
-
-`motd-container` x
-
-`motd` 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.
+
+`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` x
`switch` x
`targets` x
-
-`termlists` x
----
`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