X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=1d654393e0781b156d7ea651cf30ab39d9723cc2;hb=f426841825d1f16c9080ad4fecb6c880ace9b521;hp=4a177984f3c1bcb701256e3e5c957aacfdec5aab;hpb=39089b1aed45657df6653db00e1bc5ee1d6a46f4;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 4a17798..1d65439 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -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 @@ -57,18 +57,18 @@ Simple example The following is [a complete MKWS-based searching application](//example.indexdata.com/simple.html): - - - - MKWS demo client - - - - -
-
- - + + + + MKWS demo client + + + + +
+
+ + Go ahead, try it! Simply put the above in a file (e.g index.html), drop it into a folder accessible with an ordinary web-server (e.g @@ -141,16 +141,17 @@ The main widgets are: To see all of these working together, just put them all into the HTML `` like so: -
-
-
-
-
-
-
+
+
+
+
+
+
+
The full set of supported widgets is described in the -reference guide below. +reference guide +[below](#widgets). Widget team ----------- @@ -170,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 =================== @@ -196,23 +181,21 @@ Many aspects of the behaviour of MKWS can be modified by setting parameters into the `mkws_config` object. So the HTML header looks like this: - - + + 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 @@ -220,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: @@ -237,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 @@ -266,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. @@ -322,9 +305,9 @@ Inline Handlebars templates are distinguished from Javascript via a `type="text/x-handlebars-template"` attribute. For example, to override the pager template you would include this in your document: - + The Facet template has a special feature where you can override it on a per-facet basis by adding a dash and the facet name as a suffix eg. @@ -359,7 +342,7 @@ see what is being returned with each search result in the list. In order for this to work you'll need to enable verbose output from Handlebars which is done by including this line or similar: - + Internationalisation -------------------- @@ -376,17 +359,17 @@ details inline, here's a summary template that will link directly to the source via the address provided in the metadata as the first element of `md-electronic-url`: - + For a more involved example where markup for multiple widgets is decorated with [Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is @@ -418,10 +401,10 @@ generally visible on the page is a search box, and the results appear in a popup. The key part of such an application is this invocation of the MKWS jQuery plugin: -
-
-
-
+
+
+
+
The necessary scaffolding can be seen in an example application, [popup.html](http://example.indexdata.com/popup.html). @@ -560,36 +543,42 @@ 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 -containing the username, a slash, and the password: +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" }; + mkws_config = { sp_auth_credentials: "mike/swordfish" }; ### (Optional): conceal credentials from HTML source -Using a credential-based Service-Proxy authentication URL such as the -one above reveals the the credentials to public view -- to anyone who -does View Source on the MKWS application. This may be acceptable for -some libraries, but is intolerable for those which provide -authenticated access to subscription resources. - -In these circumstances, a more elaborate approach is necessary. The -idea is to make a URL local to the customer that is used for -authentication onto the Service Proxy, hiding the credentials in a -local rewrite rule. Then local mechanisms can be used to limit access -to that local authentication URL. Here is one way to do it when +Using credential-based authentication settings such as those above +reveals the the credentials to public view -- to anyone who does View +Source on the MKWS application. This may be acceptable for some +libraries, but is intolerable for those which provide authenticated +access to subscription resources. + +In these circumstances, a different approach is +necessary. Referer-based or IP-based authentication may be +appropriate. But if these are not possible, then a more elaborate +approach can be used to hide the credentials in a web-server +configuration that is not visible to users. + +The idea is to make a Service Proxy authentication URL local to the +customer, hiding the credentials in a rewrite rule in the local +web-server's configuration. Then local mechanisms can be used to limit +access to that local authentication URL. Here is one way to do it when Apache2 is the application's web-server, which we will call -yourname.com: +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 +Step 3: protect access to the local path `http://yourname.com/spauth/` (e.g. using a `.htaccess` file). @@ -632,102 +621,461 @@ attribute as follows: Reference guide =============== -Configuration object --------------------- +Widgets +------- -The configuration object `mkws_config` may be created before including -the MKWS JavaScript code to modify default behaviour. This structure -is a key-value lookup table, whose entries are described in the table -below. All entries are optional, but if specified must be given values -of the specified type. If ommitted, each setting takes the indicated -default value; long default values are in footnotes to keep the table -reasonably narrow. +The following widgets are provided in the core set. (Others can be +added: see the [MKWS developers' guide](mkws-developer.html).) ---- -Element Type Default Description --------- ----- --------- ------------ -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. - -facets array *Note 1* Ordered list of names of facets to display. Supported facet names are - `xtargets`, `subject` and `author`. +Name Description +---- ----------- +`auth-name` Initially empty, it updates itself to shows the name + of the library that the application is logged in as + when authentication is complete. + +`builder` A button which, when pressed, analyses the current + settings of the team that it is a part of, and + generates the HTML for an auto-searching element + that will replicate the present search. This HTML is + displayed in an alert box: it is intended that this + widget be subclassed to store the generated widget + definitions in more useful places. + +`button` The search button. Usually generated a `search` + widget. + +`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` 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` 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 + ` +
-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, +and how `service_proxy_auth` is assembled from +`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`. Language specification ---------------------- @@ -739,13 +1087,13 @@ French. Then value of this entry must be a key-value lookup table, mapping the English-language strings of the UI into their equivalents in the specified language. For example: - var mkws_config = { - language_French: { - "Authors": "Auteurs", - "Subjects": "Sujets", - // ... and others ... - } - } + var mkws_config = { + language_French: { + "Authors": "Auteurs", + "Subjects": "Sujets", + // ... and others ... + } + } The following strings occurring in the UI can be translated: `Displaying`, @@ -755,7 +1103,7 @@ The following strings occurring in the UI can be translated: `Search`, `Sort by`, `Targets`, -`Termlists`, +`Facets`, `and show`, `found`, `of`, @@ -789,18 +1137,18 @@ 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: - - + + -
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
---- Element Type Default Description @@ -830,68 +1178,92 @@ 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-termlists`, so as to avoid inadvertently styling other +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 - - #mkwsBlanket - (no contents -- used only for masking) - - #mkwsResults - 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) - table - tbody - tr* - th - td - #mkwsTargets - #mkwsBytarget - table - thead - tr* - td* - tbody - tr* - td* - - #mkwsStat - span.head - span.clients - span.records + #mkwsSwitch + a* + + #mkwsLang + ( a | span )* + + #mkwsSearch + form + input#mkwsQuery type=text + input#mkwsButton type=submit + + #mkwsBlanket + (no contents -- used only for masking) + + #mkwsResults + 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) + table + tbody + tr* + th + td + #mkwsTargets + #mkwsBytarget + table + thead + tr* + td* + tbody + tr* + td* + + #mkwsStat + span.head + span.clients + span.records + + +Appendix: compatibility roadmap +=============================== + +FIXME: more to write here. + + +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. + - - -