X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=9abebd545eaafd1ae642d660d009bcdd3eb83084;hb=ec703eca35bf0c61b49fee4dced172229f796a99;hp=61b5c96c1778cdc637e6ddf5de18658058e966bb;hpb=a091348aabc6efb4e000682a20c67e0042c1bd13;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 61b5c96..9abebd5 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -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
-----------
@@ -196,15 +197,15 @@ 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
@@ -266,7 +267,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 +323,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 +360,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 +377,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 +419,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).
@@ -555,49 +556,36 @@ that can be used when running an application from a different URL. But
if multiple Referring URLs are needed, then each must be specified in
its own User Access record.
-### Tell the application to use the library
-
-In the HTML of the application, tell MKWS to authenticate on to the
-Service Proxy. When referer-based or IP-based authentication is used,
-this is very simple:
-
-
-
-> TODO This should be the default setting: see **MKWS-251**.
-
-And ensure that access to the MWKS application is from the correct
-Referrer URL or IP-range.
-
### (Optional): embed credentials for access to the library
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 can most simply be done just
-by setting the `service_proxy_auth` configuration item to a URL such as
-`//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish`
+Proxy when establishing the session. This is done
+by setting the `sp_auth_credentials` configuration item to a string
+containing the username and password separated by a slash:
-> TODO It should be possible to add the username and password to the
-> configuration without needing to repeat the rest of the URL: see
-> **MKWS-254**.
+ 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:
@@ -605,9 +593,9 @@ Step 1: add a rewriting authentication alias to the configuration:
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
-
+`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).
@@ -650,6 +638,208 @@ attribute as follows:
Reference guide
===============
+Widgets
+-------
+
+The following widgets are provided in the core set. (Others can be
+added: see the [MKWS developers' guide](mkws-developer.html).)
+
+----
+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 items 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
+ `
-
+
+
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
----
Element Type Default Description
@@ -848,68 +1038,68 @@ 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
- - -