% The MKWS manual: embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% October 2014
+% November 2014
Introduction
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
-------- ------ ----- --------- ------------
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).
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.
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.
The properties of the `popup` widget are as follows:
----
-Element Type Default Description
+Setting Type Default Description
-------- ----- ------- ------------
popup_width int 880 Width of the popup window, in pixels.
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