% The MKWS manual: embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% October 2014
+% November 2014
Introduction
When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
-Proxy when establishing the session. This is done
+Proxy when establishing the session. This is done
by providing the `sp_auth_credentials` configuration setting as a string
containing the username and password separated by a slash:
found for the current search, any diagnostics they
have returned, the number of records that have been
returned for display, and the connection state.
+
+`waiting` An image, defaulting to <http://mkws.indexdata.com/progress.gif> unless overridden with the `src` configuration
+ item, which is initially invisible, appears when a search is submitted, and disappears when the search is
+ complete.
+
----
default values are in footnotes to keep the table reasonably narrow.
----
-Element Widget Type Default Description
+Setting Widget Type Default Description
-------- ------ ----- --------- ------------
-auth_hostname _global_ string If provided, overrides the `pp2_hostname` setting when constructing the
- Service Proxy authentication URL. This need only be used when authentication
- is performed on a different host from the remaining operations (search,
- retrieve, etc.)
-
autosearch facet, string If provided, this setting contains a query which is immediately run on behalf
facets, of the team. Often used with an [indirect setting](#indirect-settings).
record,
facets _team_ array *Note 1* Ordered list of names of facets to display.
-lang _team_ string Two-letter ISO code of the default language to display the UI in. Supported
+lang _team_ string The 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).
records, chapter of the Pazpar2 manual
results ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
-log_level _global_ int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
- datestamps, 3 = messages with datestamps and stack-traces.
+log_level _global_ string info The lowest level of logging output to emit. Acceptable values are
+ `trace`, `debug`, `info`, `warn`, `error` and `fatal`.
maxrecs facet, int Limits the metasearching middleware to retrieving no more than the specified
facets, number of records from each target.
records,
results
+newsearch_opacity records, float If defined, a fractional value between in the range 0.0 (transparent) to 1.0
+ facets (opaque). When a new search is submitted, the widget fades to that opacity
+ (reverting to full opacity when data arrives).
+
paragraphs reference int Limits the number of paragraphs rendered to the specified number. If
omitted, there is no limit.
service_proxy_auth _global_ url If defined, this is the 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. When not defined, the URL is assembled from `auth_hostname` or
- `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and
+ in. When not defined, the URL is assembled from `sp_auth_hostname` or
+ `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and
`sp_auth_credentials`. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
section below.
-sp_auth_path _global_ string *Note 6* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_hostname _global_ string If provided, overrides the `pp2_hostname` setting when constructing the
+ Service Proxy authentication URL. This need only be used when authentication
+ is performed on a different host from the remaining operations (search,
+ retrieve, etc.)
+
+sp_auth_path _global_ string Part of the URL used for authentication. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
-sp_auth_query _global_ string *Note 7* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_query _global_ string *Note 6* Part of the URL used for authentication. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
+src waiting url The address of an image to use in the `waiting` widget in place of the
+ default spinning wheel. Used to indicate that a search is in progress.
+
target facet, string One of three ways to select which targets an auto-searching widgets uses. See
facets, the [Choosing targets from the library](#choosing-targets-from-the-library)
record, section above.
switch,
targets
-<!--- The widget called "record" is a special-case of "records"; both also use "summary" -->
-
text builder string "Build!" Specifies what text to use for the Builder button.
use_service_proxy _global_ bool true If true, then a Service Proxy is used to deliver searching services rather
3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
-4. The default for `pp2_path` is `"service-proxy"`
+4. The default for `pp2_path` is `"service-proxy/"`
5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
-6. The default for `sp_auth_path` is `"service-proxy/"`.
-
-7. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
### Indirect settings
### Assembling Pazpar2 URLs
-FIXME describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`; and how `service_proxy_auth` is assembled from
-`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
+Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
+assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
+endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
+
+In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
+is generally made to the same endpoint as the other requests. However, the hostname used for authentication may if necessary be
+overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
+`sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
+
+So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
+(sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
+and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
+URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.
Language specification
----------------------
}
The following strings occurring in the UI can be translated:
-`Displaying`,
-`Next`,
-`Prev`,
-`Records`,
-`Search`,
-`Sort by`,
-`Targets`,
-`Facets`,
-`and show`,
-`found`,
-`of`,
-`per page`
-and
-`to`.
+
+* `Search complete: found`
+* `records`
+* `Displaying`
+* `to`
+* `of`
+* `found`
+* `Prev`
+* `Next`
+* `Sort by`
+* `and show`
+* `per page`
+* `Search`
+* `Active clients`
+* `Retrieved records`
+* `Records`
+* `Targets`
+* `Target ID`
+* `Hits`
+* `Diags`
+* `Records`
+* `State`
In addition, facet names can be translated:
-`Authors`,
-`Sources`
-and
-`Subjects`.
+
+* `Authors`
+* `Sources`
+* `Subjects`
+
+and whatever field captions are defined by `facet_caption_*` settings.
+
+And sort-orders:
+
+* `relevance`
+* `title`
+* `newest`
+* `oldest`
+
+and whatever sort-orders are defined by the `sort_options` setting.
Finally, the names of fields in the full-record display can be
translated. These include, but may not be limited to:
-`Author`,
-`Date`,
-`Location`,
-`Subject`
-and
-`Title`.
-
+* `Title`
+* `Date`
+* `Author`
+* `Links`
+* `Subject`
+* `Locations`
jQuery UI popup invocation
--------------------------
The MasterKey Widget Set can be invoked in a popup window on top of the page.
-Note that when using the `popup` layout, facilities from the jQuery UI
-toolkit are used, so it's necessary to include both CSS and JavaScript
-from that toolkit. The relevant lines are:
+Note that the `popup` widget uses facilities from the jQuery UI, so
+it's necessary to include both CSS and JavaScript from that
+toolkit. The relevant lines are:
<script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
<link rel="stylesheet" type="text/css"
<div class="mkws-stat"></div>
</div>
+Popup windows can contain any HTML, not just MKWS widgets.
+
+The properties of the `popup` widget are as follows:
+
----
-Element Type Default Description
+Setting Type Default Description
-------- ----- ------- ------------
-popup_width string 880 Width of the popup window (if used), in
- pixels.
+popup_width int 880 Width of the popup window, in pixels.
-popup_height string 760 Height of the popup window (if used), in
- pixels.
+popup_height int 760 Height of the popup window, in pixels.
-popup_button string `input.mkwsButton` A click on this selector will trigger the
- popup to open
+popup_button string `input.mkwsButton` A jQuery selector identifying the element which, which clicked, pops up the window.
-popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
+popup_modal bool 0 Indicates whether the popup is modal (blocks access to the background page until
+ dismissed). Set to 1 if a modal popup is required.
-popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
+popup_autoOpen bool 1 Indictaes whether to pop up the window automatically when the page is loaded.
----
-You can have more than one mkws-popup widgets on a page. Please use a different
-popup_button value to address the right ones.
+Multiple `popup` widgets can co-exist on a page. In this case, different
+`popup_button` values must be used for each.
-The structure of the HTML generated by the MKWS widgets
--------------------------------------------------------
+Structure of HTML generated by widgets
+--------------------------------------
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-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
-and .CLASS indicates an instance of a class.
-
- #mkwsSwitch
- a*
-
- #mkwsLang
- ( a | span )*
+Set, it's necessary to understand the structure of the HTML elements that are
+generated within the widgets. The HTML structure is as follows. As in CSS,
+_.class_ indicates an instance of a class. A trailing `*` indicates zero or
+more instances; a trailing `?` indicates zero or one instance.
+
+ .mkws-progress
+ span.mkws-done
+ span.mkws-waiting
- #mkwsSearch
- form
- input#mkwsQuery type=text
- input#mkwsButton type=submit
+ .mkws-search
+ form.mkws-search-form
+ input.mkws-query
+ input.mkws-button
- #mkwsBlanket
- (no contents -- used only for masking)
-
- #mkwsResults
+ .mkws-results
table
tbody
tr
- td
- #mkwsTermlists
- div.title
- div.facet*
- div.termtitle
- ( a span br )*
- td
- div#mkwsRanking
- form#mkwsSelect
- select#mkwsSort
- select#mkwsPerpage
- #mkwsPager
- #mkwsNavi
- #mkwsRecords
- div.record*
- span (for sequence number)
- a (for title)
- span (for other information such as author)
- div.details (sometimes)
+ td.mkws-facets-container-wide
+ div.mkws-facets
+ div.mkws-facet*
+ div.mkws-facet-title
+ div.mkws-term*
+ a
+ span
+ td.mkws-motd-container
+ div.mkws-ranking
+ form
+ select.mkws-sort
+ option*
+ select.mkws-perpage
+ option*
+ div.mkws-pager
+ div
+ div
+ span.mkws-prev
+ span.mkws-current-page
+ a*
+ span.mkws-next
+ div.mkws-navi
+ div.mkws-records
+ div.mkws-summary*
+ div.mkws-field-data
+ span.mkws-field-NAME*
+ div.mkws-details?
table
tbody
tr*
th
td
- #mkwsTargets
- #mkwsBytarget
- table
- thead
- tr*
- td*
- tbody
- tr*
- td*
+ tr
+ td
+ div.mkws-facets-container-narrow
+
+ .mkws-targets
+ table
+ thead
+ tr
+ td*
+ tbody
+ tr*
+ td*
- #mkwsStat
- span.head
- span.clients
- span.records
-
Appendix: compatibility roadmap
===============================
-FIXME: more to write here.
+Wherever possible, we ensure that all functional changes in MKWS are
+backwards-compatible, so that applications written against old versions of the
+toolkit will continue to work when running against newer versions.
+
+However, a few aspects of functionality unavoidably change in backwards
+incompatible ways. We ensure that **this only happens with new major
+versions** -- so it should _always_ be safe to upgrade to a new minor version.
+As an aid to porting old applications, we here note the specific
+backwards-incompatible changes in the various major releases, and those
+planned for future major releases.
-Old and new-style class-names
------------------------------
+Major version 1.x
+-----------------
-**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
-without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
-used to specify team names used an `mkwsTeam_` prefix (with an
-underscore). So instead of `mkws-team-foo`, it used to be
-`mkwsTeam_foo`.
+Versions of MKWS before v1.0 (including the only prior release, v0.9.1) used
+camel-case class-names: without hyphens and with second and subsequent words
+capitalised. So instead of `mkws-search`, it used to be `mkwsSearch`. And the
+classes used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be `mkwsTeam_foo`.
The 1.x series of MKWS releases recognise these old-style class-names
as well as the canonical ones, as a facility for backwards
projects / mkws-moved-to-github.git / blobdiff