% 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:
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.
}
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
-------- ----- ------- ------------
-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