% The MKWS manual: embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% October 2014
+% November 2014
Introduction
[Drupal](https://www.drupal.org/)
sites.
-All of these approaches require programming to a greater or lesser
+All but the last of these approaches require programming to a greater or lesser
extent. Against this backdrop, we introduced
[MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
-- a set of simple, very high-level HTML+CSS+JavaScript
Widgets that do not have a team specified (as in the examples above)
are placed in the team called `AUTO`.
-Old and new-style class-names
------------------------------
-
-**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`.
-
-The 1.x series of MKWS releases recognise these old-style class-names
-as well as the canonical ones, as a facility for backwards
-compatibility. However, **these old class-names are deprecated, and
-support will be removed in v2.0**. Existing applications that use them
-should be upgraded to the new-style class names as soon as convenient.
-
Configuring widgets
===================
lang_options: [ "en", "da" ]
lang: "da",
sort_default: "title",
- query_width: 60
};
</script>
<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
This configuration restricts the set of available UI languages English
and Danish (omitting German), sets the default to Danish (rather than
-the English), initially sorts search results by title rather than
-relevance (though as always this can be changed in the UI) and makes
-the search box a bit wider than the default.
+the English), and initially sorts search results by title rather than
+relevance (though as always this can be changed in the UI).
-The full set of supported configuration items is described in the
+The full set of supported configuration settings is described in the
reference guide below.
Per-widget configuration
In addition to the global configuration provided by the `mkws_config`
object, individual widgets' behaviour can be configured by providing
-configuration items as attributed on their HTML elements. For example,
+configuration settings as attributes on their HTML elements. For example,
a `records` widget might be restricted to displaying no more than
three records by setting the `numrecs` parameter as follows:
For first form is more convenient; the second is more correct.
-Because some configuration items take structured values rather than
+Because some configuration settings take structured values rather than
simple strings, they cannot be directly provided by inline
attributes. To allow for this, the special attribute
`data-mkws-config`, if provided, is parsed as JSON and its key-value
-pairs set as configuration items for the widget in question. For
+pairs used as configuration settings for the widget in question. For
example, the value of `lang_options` is an array of strings specifying
which of the supported UI languages should be made available. The
following invocation will limit this list to only English and Danish
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
-by setting the `sp_auth_credentials` configuration item to a string
+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:
mkws_config = { sp_auth_credentials: "mike/swordfish" };
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
+Step 2: set the MKWS configuration setting `service_proxy_auth` to
`http://yourname.com/spauth/`.
Step 3: protect access to the local path `http://yourname.com/spauth/`
`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
+ only way to set configuration settings at the team
level.
`console-builder` Like the `builder` widget, but emits the generated
`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
+ by the widget's `facet` configuration setting, which
may conveniently be done by means of the
`data-mkws-facet` attribute on the HTML
element. The supported facets are "subject",
`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,
+ is specified by the `facets` configuration setting,
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
+ setting is an array of zero or more strings, each
naming a facet.
`google-image` A specialisation of the `images` widget which
`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
+ configuration setting, whose value is an array of
two-letter language codes).
`log` Initially empty, this widget accumulates a log of
`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
+ available set of page-sizes can be specified as the
+ `perpage_options` configuration setting, whose value is
an array of integers. The initial selected value can
- be set by the `perpage_default` configuration item.
+ be specified by the `perpage_default` configuration setting.
`progress` Shows a progress bar which indicates how many of the
targets have responded to the search.
record.)
`reference` A short summary about a subject specified by the
- `autosearch` configuration item. This is created by
+ `autosearch` configuration setting. 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
`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
+ available set of sort criteria can be specified as the
+ `sort_options` configuration setting, 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.
+ value can be specified by the `sort_default` configuration
+ setting.
`stat` A summary line stating how many targets remain
active, how many records have been found, and how
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
--------- ------ ----- --------- ------------
-auth_hostname
-
-autosearch
-
-facet
-
-facet_caption_*
-
-facet_max_*
-
-facets array *Note 1* Ordered list of names of facets to display. Supported facet names are
- `xtargets`, `subject` and `author`.
-
-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).
-
-lang_options array [] A list of the languages to offer as options. If empty (the default), then all
- configured languages are listed.
-
-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.
-
-limit
-
-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.
-
-maxrecs
-
-paragraphs
-
-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.
-
-perpage
-
-perpage_default string 20 The initial value for the number of records to show on each page.
-
-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.
-
-pp2_hostname
-
-pp2_path
-
-query
-
-query_width int 50 The width of the query box, in characters.
-
-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.
-
-scan_all_nodes
-
-sentences
-
-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.
-
-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`.
-
-show_lang bool true Indicates whether or not to display the language menu.
-
-show_perpage bool true Indicates whether or not to display the perpage menu.
-
-show_sort bool true Indicates whether or not to display the sort menu.
-
-show_switch bool true Indicates whether or not to display the switch menu, for switching between
- showing retrieved records and target information.
+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).
+ record,
+ records,
+ results
+
+facet facet string For a `facet` widget, this setting is mandatory, and indicates which field to
+ list terms for. Three fields are supported: `subject`, `author` and
+ `xtargets` -- the latter a special case which treats the target providing a
+ record as a facet. Any other field may also be used, but the default caption
+ and maximum term-count may not be appropriate, needing to be overridden by
+ `facet_caption_*` and `facet_max_*` settings.
+
+facet_caption_* facet string Specifies what on-screen caption is to be used for the named facet: for
+ example, if a `date` facet is generated, then `facet_caption_date` can be
+ used to set the caption to "Year".
+
+facet_max_* facet int Specifies how many terms are to be displayed for the named facet: for
+ example, if a `publisher` facet is generated, then `facet_max_publisher` can
+ be used to limit the list to the top six.
+
+facets _team_ array *Note 1* Ordered list of names of facets to display.
+
+freeze_opacity records float If defined, a fractional value between in the range 0.0 (transparent) to 1.0
+ (opaque). During the short period after a mouse-move over the records when
+ the display will not be updated, the widget is faded to that opacity
+ (reverting to full opacity when the period elapses or the mouse leaves the
+ area).
+
+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).
+
+lang_options lang array [] A list of the languages to offer as options. If empty (the default), then all
+ configured languages are listed.
+
+language_* _global_ 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.
+
+limit facet, string Allows a partial search to be included in the specification of an
+ facets, auto-executing widget. This is ANDed with the submitted query, as though it
+ record, had been selected from a facet. See the Search section in [the Protocol
+ records, chapter of the Pazpar2 manual
+ results ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
+
+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.
+ record,
+ 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.
+
+pazpar2_url _global_ string If specified, this is the URL used to access the metasearch middleware. This
+ service must be configured to provide search results, facets, etc. It may be
+ either unmediated Pazpar2 or the MasterKey Service Proxy, which mediates
+ access to an underlying Pazpar2 instance. When not specified, the URL is
+ assembled from `pp2_hostname` and `pp2_path`. See the [Assembling Pazpar2
+ URLs](#assembling-pazpar2-urls) section below.
+
+perpage facet, int Specifies the number of records to show per page in an auto-executing
+ facets, widget. Contrast with `perpage_default`, which is used to prime the dropdown
+ record, with which a user chooses the page-size in an interactive session.
+ records,
+ results
+
+perpage_default _team_ string 20 The initial value for the number of records to show on each page.
+
+perpage_options ranking array *Note 2* A list of candidate page sizes. Users can choose between these to determine
+ how many records are displayed on each page of results.
+
+pp2_hostname _global_ string *Note 3* Unless overridden by the `pazpar2_url` setting, this is used together with
+ `pp2_path` to construct the URL to the Pazpar2 service (or Service
+ Proxy). Set this to connect to a service on a different host from the
+ default.
+
+pp2_path _global_ string *Note 4* Unless overridden by the `pazpar2_url` setting, this is used together with
+ `pp2_hostname` to construct the URL to the Pazpar2 service (or Service
+ Proxy). Set this to connect to a service on a different host from the
+ default.
+
+scan_all_nodes _global_ bool false An internal setting that changes how MKWS scans the HTML documen to discover
+ widgets. If set to true, a different approach is used which may be faster
+ under some circumstances.
+
+sentences reference int Limits the number of sentences 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 `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.
+
+service_proxy_auth_domain _global_ domain When the server used for authentication -- e.g. the one identified by the
+ `service_proxy_auth` URL -- proxies for different server, this can be set to
+ the domain of the server that it proxies for, so that cookies are rewritten
+ to appear to be from this domain.
+
+show_lang lang bool true Indicates whether or not to display the language menu.
+
+show_perpage ranking bool true Indicates whether or not to display the perpage menu.
+
+show_sort ranking bool true Indicates whether or not to display the sort menu.
+
+show_switch switch bool true Indicates whether or not to display the switch menu.
+
+sort facet, string Specifies the order in which to sort the records retrieved by an
+ facets, auto-executing widget. Must be one of those in the `sort_options`
+ record, array. Contrast with `sort_default`, which is used to prime the dropdown
+ records, with which a user chooses the sortorder in an interactive session.
+ results
+
+sort_default _team_ string relevance The default sort criterion to use. Must be one of those in the
+ `sort_options` array.
+
+sort_options ranking array *Note 5* 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`.
+
+sp_auth_credentials _global_ string If defined, this must be a slash-separated combination of username and
+ password, which is sent as the authentication credentials on session
+ initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
+ section below.
+
+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 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.
+ records,
+ results
+
+targetfilter 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.
+ records,
+ results
+
+targets 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.
+ records,
+ results
+
+template details, string Numerous widgets use Handlebars templates to render HTML. In general, each
+ done, of these by default uses a template with the same name as the widget
+ facet, itself. Individual widgets can be customised to use a template of a
+ facets, different name by means of their `template` setting. The `records` widget
+ images, (and `record`, an equivalent that shows only a single record) use the
+ lang, `summary` template as well as the `records` template.
+ navi,
+ pager,
+ progress,
+ ranking,
+ records,
+ reference,
+ results,
+ search,
+ stat,
+ switch,
+ targets
+
+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
+ than raw Pazpar2. An authentication phase is run during initialisation.
+----
-sort
+The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
+widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
+customise the display than by providing a full HTML structure.
-sort_default string relevance The label of the default sort criterion to use. Must be one of those in the
- `sort` array.
+### Notes
-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`.
+1. The default for `facets` is `["xtargets", "subject", "author"]`
-sp_auth_credentials
+2. The default for `perpage_options` is `[10, 20, 30, 50]`
-sp_auth_path
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
-sp_auth_query
+4. The default for `pp2_path` is `"service-proxy/"`
-target
+5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
-targetfilter
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
-targets
+### Indirect settings
-template
+The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
+example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
+query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
-text
+The currently supported types are:
-use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than
- raw Pazpar2.
-----
+* `param` -- uses the value of the specified query parameter for the URL. For example
+`<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
+invoked from the URL `http://example.com/magic/example.html?term=sushi`
-Perhaps we should get rid of the `show_lang`, `show_perpage`,
-`show_sort` and `show_switch` configuration items, and simply display the relevant menus
-only when their containers are provided -- e.g. an `mkws-lang` element
-for the language menu. But for now we retain these, as an easier route
-to lightly customise the display than my changing providing a full HTML
-structure.
-
-### Notes
+* `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
+`!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
+invoked from the URL `http://example.com/magic/lookup/dinosaur`
-1. ["sources", "subjects", "authors"]
+* `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
+ search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
+ extraction and reversing, the use the HTML:
-2. /pazpar2/search.pz2
+<!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
-3. [10, 20, 30, 50]
+ <script>var _reversedParam = extractAndReverse("term");</script>
+ <div class="mkws-results" autosearch="!var!_reversedParam">
-4. http://sp-mkws.indexdata.com/service-proxy-auth
+### Assembling Pazpar2 URLs
-5. http://sp-mkws.indexdata.com/service-proxy/
+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.
-6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+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 )*
-
- #mkwsSearch
- form
- input#mkwsQuery type=text
- input#mkwsButton type=submit
+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
- #mkwsBlanket
- (no contents -- used only for masking)
+ .mkws-search
+ form.mkws-search-form
+ input.mkws-query
+ input.mkws-button
- #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
+===============================
+
+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.
+
+
+Major version 1.x
+-----------------
+
+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
+compatibility. However, **these old class-names are deprecated, and
+support will be removed in v2.0**. Existing applications that use them
+should be upgraded to the new-style class names as soon as convenient.
+
- - -
projects / mkws-moved-to-github.git / blobdiff