X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=2ccc9beec14dd0156a22e671483c178beea7cd15;hb=4416bf8226923c047630fa0f5e219ed96fe72f01;hp=61b5c96c1778cdc637e6ddf5de18658058e966bb;hpb=a091348aabc6efb4e000682a20c67e0042c1bd13;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 61b5c96..2ccc9be 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,13 +141,13 @@ 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.
@@ -196,15 +196,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
@@ -322,9 +322,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 +359,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 +376,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 +418,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 +555,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 +592,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).
@@ -757,13 +744,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`,
@@ -807,18 +794,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
@@ -854,62 +841,62 @@ 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
- - -