X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=1066f63fadbff802bb0157b2a2edaf04ee3b2944;hb=7d7a5862b72296ef76b6f4f5cfb7b0e89147b6a3;hp=46f507c4bc9b0f9baf52653c56f2ab556d63f964;hpb=fc6dc0499a3e9911e516ce1345e2293616bb4234;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 46f507c..1066f63 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 =================== @@ -202,18 +186,16 @@ like this: lang_options: [ "en", "da" ] lang: "da", sort_default: "title", - query_width: 60 }; 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 @@ -221,7 +203,7 @@ 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: @@ -238,11 +220,11 @@ attributes prefixed with `data-mkws-`, so: 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 @@ -267,7 +249,7 @@ etc., customised layouts may wish to treat each of these components separately. In this case, `mkws-results` can be omitted, and the following lower-level widgets provided instead: -* `mkws-termlists` -- provides the facets +* `mkws-facets` -- provides the facets * `mkws-ranking` -- provides the options for how records are sorted and how many are included on each page of results. @@ -560,8 +542,8 @@ 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 -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" }; @@ -590,9 +572,10 @@ yourname.com`: Step 1: add a rewriting authentication alias to the configuration: RewriteEngine on - RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P] + 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/` @@ -659,171 +642,444 @@ Name Description widget be subclassed to store the generated widget definitions in more useful places. -`button` x +`button` The search button. Usually generated a `search` + widget. -`categories` x +`categories` Obtains from the Service Proxy a list of the target + categories associated with the library in use, and + displays them in a drop-down list. When a category + is selected, searches are limited to the targets + that are part of that category. -`config` x +`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 settings at the team + level. `console-builder` Like the `builder` widget, but emits the generated HTML on the JavaScript console. This exists to provide an example of how to subclass the `builder` widget. -`cover-art` x - -`details` x - -`done` x - -`facet` x - -`google-image` x - -`images` x - -`lang` x - -`log` x - -`lolcat` x - -`motd-container` x - -`motd` x - -`navi` x - -`pager` x - -`per-page` x - -`progress` x - -`query` x - -`ranking` x - -`record` x - -`records` x - -`reference` x - -`results` x +`cover-art` Displays cover art for a book by searching in + Amazon. Often used with an `autosearch` attribute to + indicate what book to display. For example, + `
` + displays cover art for _All Yesterdays: Unique and + Speculative Views of Dinosaurs and Other Prehistoric + Animals_. + For this widget to work, a library that includes the + AmazonBooks target must be used. For example, the + "DEMO AmazonBooks for MKWS" account, which can be + selected with `sp_auth_credentials="mkws-amazon/mkws"`. + +`details` This widget is generated by the toolkit itself to + hold the full details of records that are initially + listed in summary form. + +`done` Initially empty, this widget is set to display + "Search complete: found _n_ records" when all + targets have completed their work, either returning + a hit-count or an error. The message displayed can + be changed by overriding the `done` template using + ` +