X-Git-Url: http://git.indexdata.com/?p=mkws-moved-to-github.git;a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=41fc31f464fe82931fd5ea30bc42a62c060177fe;hp=99513df2250ecc1884728180e57b693ea9b0cf78;hb=00204cd716f392cbde47cd5371a663241c46710d;hpb=4428c73bfc09fb75a81daab4711268f58657c80b diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 99513df..41fc31f 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -1,6 +1,6 @@ % The MKWS manual: embedded metasearching with the MasterKey Widget Set % Mike Taylor -% October 2014 +% November 2014 Introduction @@ -41,7 +41,7 @@ flexibility against convenience: [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 @@ -171,22 +171,6 @@ is part of the `aux` team. 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 =================== @@ -558,7 +542,7 @@ its own User Access record. 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: @@ -836,6 +820,11 @@ Name Description 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 unless overridden with the `src` configuration + item, which is initially invisible, appears when a search is submitted, and disappears when the search is + complete. + ---- @@ -856,13 +845,8 @@ the relevant widgets are listed. All entries are optional, but if specified must 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, @@ -886,7 +870,13 @@ facet_max_* facet int Specifies how many terms a 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 +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). @@ -903,8 +893,8 @@ limit facet, string Allows a partial search to 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. @@ -912,6 +902,10 @@ maxrecs facet, int Limits the metasearching m 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. @@ -943,11 +937,6 @@ pp2_path _global_ string *Note 4* Unless overridden by the ` Proxy). Set this to connect to a service on a different host from the default. -responsive_design_width _global_ int If defined, then the facets display moves between two locations as the - screen-width varies. The specified number is the threshhold width, in - pixels, at which the facets move between their two locations. The `switch` - and `lang` widgets also disappear entirely below this threshhold. - 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. @@ -958,8 +947,8 @@ sentences reference int Limits the number of sente 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. @@ -968,13 +957,13 @@ service_proxy_auth_domain _global_ domain When the server used for a 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_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_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_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. +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` @@ -995,12 +984,20 @@ sp_auth_credentials _global_ string If defined, this must be a 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. @@ -1037,8 +1034,6 @@ template details, string Numerous widgets use Handl 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 @@ -1057,26 +1052,52 @@ customise the display than by providing a full HTML structure. 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 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. FIXME -say more. +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_. + +The currently supported types are: -FIXME !query!q, !path!2, etc. +* `param` -- uses the value of the specified query parameter for the URL. For example +`
` 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` + +* `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` + +* `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: + + + + +
### 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 ---------------------- @@ -1097,46 +1118,64 @@ in the specified language. For example: } 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:
+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 `
` 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 +=============================== + +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. + - - -