% 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
Simple Example
---------------
+==============
The following is a complete MKWS-based searching application:
<div id="mkwsTargets"></div>
<div id="mkwsStat"></div>
+
Configuration
--------------
+=============
Many aspects of the behaviour of MKWS can be modified by setting
parameters into the `mkws_config` object. **This must be done *before*
Control over HTML and CSS
--------------------------
+=========================
More sophisticated applications will not simply place the `<div>`s
together, but position them carefully within an existing page
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
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
[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
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
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`,
MKWS Target Selection
----------------------
+=====================
MKWS accesses targets using the Pazpar2 metasearching engine. Although
Pazpar2 can be used directly, using a statically configured set of
available targets to use.
-### Maintaining the library
+Maintaining the library
+-----------------------
The service proxy accesses sets of targets that are known as
"libraries". In general, each customer will have their own library,
searching for a matching User Access record.
-### Authenticating your MWKS application onto the library
+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 backe-end site credentials stored in MKAdmin:
+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
+### Create the User Access account
-Log in to MKAdmin administrate your library:
+Log in to MKAdmin to add a User Access account for your library:
* Go to <http://mkx-admin.indexdata.com/console/>
* 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 IP-address range, or
- referring URL, or hostname.
+ 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 --
<http://yourname.com/app.html>, say -- you can set the User Access
that this is not secure, as other applications can use this virtual
hostname to gain access to your library.**
-> TODO Authentication by IP address does not yet work correctly -- see
-> bug MKWS-234 ("Improve SP configuration/proxying for better
-> authentication").
+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,
single string separated by a slash -- e.g. "mike/swordfish" -- into
the User Access record's Authentication field.
-You can create multiple User Access records: for example, one that
-uses Referring URL, and another that uses a username/password pair to
-be used when running an application from a different URL.
+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
+### Tell the application to use the library
In the HTML of the application, tell MKWS to authenticate on to the
-Service Proxy. When IP-based, referer-based or hostname-based
-authentication is used, this is very simple:
+Service Proxy. When referer-based or IP-based authentication is used,
+this is very simple:
<script type="text/javascript">
var mkws_config = { service_proxy_auth:
"//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
</script>
-> TODO This should be the default setting
+> 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
+### (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>
+`//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)
+> 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.
+> in general change along with it: see **MKWS-253**.
-#### (Optional): embed credentials for access to the library
+### (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>
+`//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.
+> configuration without needing to repeat the rest of the URL: see
+> **MKWS-254**.
-#### (Optional): conceal credentials from HTML source
+### (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
Apache2 is the application's web-server, which we will call
yourname.com:
-- Add a rewriting authentication alias to the configuration:
+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]
+ 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/>
-- Set the MKWS configuration item `service_proxy_auth` to
- <http://yourname.com/spauth/>
-- Protect access to the local path <http://yourname.com/spauth/>
- (e.g. using a .htaccess file).
+Step 3: protect access to the local path <http://yourname.com/spauth/>
+(e.g. using a `.htaccess` file).
-### Choosing targets from the library
+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
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
to lightly customise the display than my changing providing a full HTML
structure.
-#### Notes
+### Notes
1. ["sources", "subjects", "authors"]
3. [10, 20, 30, 50]
-4. http://mkws.indexdata.com/service-proxy-auth
+4. http://sp-mkws.indexdata.com/service-proxy-auth
-5. http://mkws.indexdata.com/service-proxy/
+5. http://sp-mkws.indexdata.com/service-proxy/
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
-### jQuery UI popup invocation
+jQuery UI popup invocation
+--------------------------
The MasterKey Widget Set can be invoked in a popup window on top of the page.
</div>
----
-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
projects / mkws-moved-to-github.git / blobdiff