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.
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/`.
widget be subclassed to store the generated widget
definitions in more useful places.
-`button` x
+`button` The search button. Usually generated a `search`
+ widget.
-`categories` x
+`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` x
+`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` x
-
-`details` x
+`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.
-`done` 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.
+----
-`facet` x
-`google-image` x
+Configuration settings
+----------------------
-`images` x
+Configuration settings may be provided at the level of a indiviual widget, or a team, or globally. Per-widget configuration is
+described above; per-team settings can be placed in a `config` widget belonging to the relevant team, and will be applied to that
+team as a whole; and global settings are provided in the global variable `mkws_config`. This structure is a key-value lookup
+table, and may specify the values of many settings.
-`lang` x
+Some settings apply only to specific widgets; others to the behaviour of the tookit as a whole. When a widget does not itself have
+a value specified for a particular configuration setting, its team is consulted; and if that also does not have a value, the global
+settings are consulted. Only if this, too, is unspecified, is the default value used.
-`log` x
+The supported configuration settings are described in the table below. For those settings that apply only to particular widgets,
+the relevant widgets are listed. All entries are optional, but if specified must be given values of the specified type. 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`,
`Search`,
`Sort by`,
`Targets`,
-`Termlists`,
+`Facets`,
`and show`,
`found`,
`of`,
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>
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