X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=79b396ebdcf5a3ec41f7d28471b788a11ab22f9e;hb=ed0c8188d49fe524bb305fd44ab027fdbacb70bd;hp=d21a0b261426660640792c0c1ef09865e03de005;hpb=d6c4167440d57861d5f0453aa88dca699199a526;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index d21a0b2..79b396e 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -2,8 +2,9 @@
% Mike Taylor
% 30 July 2014
+
Introduction
-------------
+============
There are lots of practical problems in building resource discovery
solutions. One of the biggest, and most ubiquitous is incorporating
@@ -44,7 +45,7 @@ can be embedded: search-boxes, results areas, target information, etc.
Simple Example
---------------
+==============
The following is a complete MKWS-based searching application:
@@ -123,8 +124,9 @@ To see all of these working together, just put them all into the HTML
`s
together, but position them carefully within an existing page
@@ -191,10 +193,11 @@ reference guide below.
Refinements
------------
+===========
-### Message of the day
+Message of the day
+------------------
Some applications might like to open with content in the area that
will subsequently be filled with result-records -- a message of the
@@ -204,7 +207,8 @@ day, a welcome message or a help page. This can be done by placing an
search is made.
-### Customised display using Handlebars templates
+Customised display using Handlebars templates
+---------------------------------------------
Certain aspects of the widget-set's display can be customised by
providing Handlebars templates with well-known classes that begin with
@@ -238,7 +242,8 @@ For details of Handlebars template syntax, see
[the online documentation](http://handlebarsjs.com/).
-### Responsive design
+Responsive design
+-----------------
Metasearching applications may need to appear differently on
small-screened mobile devices, or change their appearance when
@@ -264,7 +269,8 @@ cases. In this case, wrap the wide-screen `mkwsTermlists` element in a
termlists should appear.
-### Popup results with jQuery UI
+Popup results with jQuery UI
+----------------------------
The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI)
can be used to construct MKWS applications in which the only component
@@ -285,7 +291,8 @@ The necessary scaffolding can be seen in an example application,
http://example.indexdata.com/index-popup.html
-### Authentication and target configuration
+Authentication and target configuration
+---------------------------------------
By default, MKWS configures itself to use a demonstration account on a
service hosted by mkws.indexdata.com. This account (username `demo`,
@@ -297,14 +304,234 @@ In order to search in a customised set of targets, including
subscription resources, it's necessary to create an account with
Index Data's hosted service proxy, and protect that account with
authentication tokens (to prevent unauthorised use of subscription
-resources). For information on how to do this, see
-[MKWS Target Selection](library-configuration.html)
+resources). For information on how to do this, see the next section.
+
+
+MKWS Target Selection
+=====================
+
+MKWS accesses targets using the Pazpar2 metasearching engine. Although
+Pazpar2 can be used directly, using a statically configured set of
+targets, this usage is unusual. More often, Pazpar2 is fronted by the
+Service Proxy (SP), which manages authentication, sessions, target
+selection, etc.
+
+This document assumes the SP is used, and explains how to go about
+making a set of targets (a "library") available, how to connect your
+MKWS application to that library, and how to choose which of the
+available targets to use.
+
+
+Maintaining the library
+-----------------------
+
+The service proxy accesses sets of targets that are known as
+"libraries". In general, each customer will have their own library,
+though some standard libraries may be shared between many customers --
+for example, a library containing all open-access academic journals.
+A library can also contain other configuration information, including
+the set of categories by which targets are classified for the library.
+
+Libraries are maintained using MKAdmin (MasterKey
+Admin). Specifically, those used by MKWS are generally maintained on
+the "MKX Admin" installation at
+
+
+In general, Index Data will create a library for each customer, then
+give the customer a username/password pair that they can use to enter
+MKAdmin and administrate that library.
+
+Once logged in, customers can select which targets to include (from
+the list of several thousand that MKAdmin knows about), and make
+customer-specific modifications -- e.g. overriding the titles of the
+targets.
+
+Most importantly, customers' administrators can add authentication
+credentials that the Service Proxy will used on their behalf when
+accessing subscription resources -- username/password pairs or proxies
+to use for IP-based authentication. Note that **it is then crucial to
+secure the library from use by unauthorised clients**, otherwise the
+customer's paid subscriptions will be exploited.
+
+Access to libraries is managed by creating one or more "User Access"
+records in MKAdmin, under the tab of that name. Each of these records
+provides a combination of credentials and other data that allow an
+incoming MKWS client to be identified as having legitimate access to
+the library. The authentication process, described below, works by
+searching for a matching User Access record.
+
+
+Authenticating your MWKS application onto the library
+-----------------------------------------------------
+
+Some MKWS applications will be content to use the default library with
+its selection of targets. Most, though, will want to define their own
+library providing a different range of available targets. An important
+case is that of applications that authenticate onto subscription
+resources by means of back-end site credentials stored in MKAdmin:
+precautions must be taken so that such library accounts do not allow
+unauthorised access.
+
+Setting up such a library is a process of several stages.
+
+### Create the User Access account
+
+Log in to MKAdmin to add a User Access account for your library:
+
+* Go to
+* Enter the adminstrative username/password
+* Go to the User Access tab
+* Create an end-user account
+* Depending on what authentication method it be used, set the
+ User Access account's username and password, or referring URL, or
+ Service Proxy hostname, or IP-address range.
+
+If your MWKS application runs at a well-known, permanent address --
+
, say -- you can set the User Access
+record so that this originating URL is recognised by setting it into
+the "Referring URL" field.
+
+If your application accesses the Service Proxy by a unique virtual
+hostname -- yourname.sp-mkws.indexdata.com, say -- you can tie the use
+of this hostname to your library by setting the User Access record's
+"Host Name" field to name of the host where the SP is accessed. **Note
+that this is not secure, as other applications can use this virtual
+hostname to gain access to your library.**
+
+Or if your application's users are coming from a well-known range of
+IP-address space, you can enter the range in the "IP Ranges"
+field. The format of this field is as follows: it can contain any
+number of ranges, separated by commas; each range is either a single
+IP address or two addresses separated by a hyphen; each IP address is
+four small integers separated by periods. For example,
+`80.229.143.255-80.229.143.255, 5.57.0.0-5.57.255.255, 127.0.0.1`.
+
+Alternatively, your application can authenticate by username and
+password credentials. This is a useful approach in several situations,
+including when you need to specify the use of a different library from
+usual one. To arrange for this, set the username and password as a
+single string separated by a slash -- e.g. "mike/swordfish" -- into
+the User Access record's Authentication field.
+
+You can set multiple fields into a single User Access record; or
+create multiple User Access records. For example, a single User Access
+record can specify both a Referring URL a username/password pair 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): access by a different virtual hostname
+
+When hostname-based authentication is in use, it's necessary to access
+the Service Proxy as the correctly named virtual host. This can be
+done by setting the `service_proxy_auth` configuration item to a
+URL containing that hostname, such as
+`//yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig`
+
+> TODO It should be possible to change just the hostname without
+> needing to repeat the rest of the URL (protocol, path, query): see
+> **MKWS-252**.
+
+> TODO When changing the SP authentication URL, the Pazpar2 URL should
+> in general change along with it: see **MKWS-253**.
+
+### (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`
+
+> 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**.
+
+### (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
+Apache2 is the application's web-server, which we will call
+yourname.com:
+
+Step 1: add a rewriting authentication alias to the configuration:
+
+ RewriteEngine on
+ RewriteRule /spauth/ http://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 3: protect access to the local path
+(e.g. using a `.htaccess` file).
+
+
+Choosing targets from the library
+---------------------------------
+
+MKWS applications can choose what subset of the library's targets to
+use, by means of several alternative settings on individual widgets or
+in the `mkws_config` structure:
+
+* `targets` -- contains a Pazpar2 targets string, typically of the form
+ "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
+ target IDs.
+ At present, these IDs can take one of two forms, depending on the
+ configuration of the Service Proxy being used: they may be based on
+ ZURLs (so a typical value would be something like
+ `pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902`)
+ or they may be UDBs (so a typical value would be something like
+ `pz:id=brown|artstor`)
+
+* `targetfilter` -- contains a CQL query which is used to find relevant
+ targets from the relvant library. For example,
+ `udb==Google_Images`
+ or
+ `categories=news`
+
+* `target` -- contains a single UDB, that of the sole target to be
+ used. For example,
+ `Google_Images`.
+ This is merely syntactic sugar for "targetfilter" with the query
+ `udb==NAME`
+
+For example, a `Records` widget can be limited to searching only in
+targets that have been categorised as news sources by providing an
+attribute as follows:
+
+
Reference Guide
----------------
+===============
-### Configuration object
+Configuration object
+--------------------
The configuration object `mkws_config` may be created before including
the MKWS JavaScript code to modify default behaviour. This structure
@@ -314,7 +541,7 @@ 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.
----
+----
Element Type Default Description
-------- ----- --------- ------------
debug_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
@@ -376,7 +603,7 @@ sort_options array *Note 6* List of supported sort criteria. Eac
use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw
Pazpar2.
----
+----
Perhaps we should get rid of the `show_lang`, `show_perpage`,
`show_sort` and `show_switch` configuration items, and simply display the relevant menus
@@ -385,7 +612,7 @@ for the language menu. But for now we retain these, as an easier route
to lightly customise the display than my changing providing a full HTML
structure.
-#### Notes
+### Notes
1. ["sources", "subjects", "authors"]
@@ -400,7 +627,8 @@ structure.
6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
-### Language specification
+Language specification
+----------------------
Support for another UI language can be added by providing an entry in
the `mkws_config` object whose name is `language_` followed by the
@@ -450,7 +678,8 @@ and
-### jQuery UI popup invocation
+jQuery UI popup invocation
+--------------------------
The MasterKey Widget Set can be invoked in a popup window on top of the page.
@@ -469,27 +698,28 @@ from that toolkit. The relevant lines are:
-
----
-Element Type Default Description
--------- ----- --------- ------------
-popup_width string 880 Width of the popup window (if used), in
- pixels.
+----
+Element Type Default Description
+-------- ----- ------- ------------
+popup_width string 880 Width of the popup window (if used), in
+ pixels.
-popup_height string 760 Height of the popup window (if used), in
- pixels.
+popup_height string 760 Height of the popup window (if used), in
+ pixels.
-popup_button string input.mkwsButton (Never change this.)
+popup_button string `input.mkwsButton` (Never change this.)
-popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
+popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
-popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
+popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
----
+----
-### The structure of the HTML generated by the MKWS widgets
+The structure of the HTML generated by the MKWS 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