--- /dev/null
+Set "Referring URL" to URL of the MKWS application, e.g.
+http://x.example.indexdata.com/mike.html
+
+Set "Host Name" to name of the host where the SP is accessed. e.g.
+sp-mkws.indexdata.com
+
+Set User Name and Password to values specified in auth URL.
+
+IP Address doesn't seem to work. Search is:
+http://mkc-admin.indexdata.com/torus2/identity.USERS/records/
+ query=ipRanges encloses/net.ipAddress "127.0.0.1"
+And that always gets hit by one of the many records with ipRanges set
+to 0.0.0.0-255.255.255.255.
% The MasterKey Widget Set
% Mike Taylor; Wolfram Schneider
-% 10 July 2014
+% 23 July 2014
Introduction
------------
-This is the MasterKey Widget Set. The initial version was based on the
-"jsdemo" application distributed with pazpar2, but it is now far
-removed from those beginnnings.
+This is the MasterKey Widget Set. It provides searching and other
+information-related functionality which can be inserted into existing
+web pages as small snippets of HTML.
As much of the searching functionality as possible is hosted on
<http://mkws.indexdata.com/>
The following files are hosted on `mkws.indexdata.com`:
-* `mkws.js`
+* `mkws.js` (and its compressed version `mkws.min.js`)
* `/pazpar2/js/pz2.js`
-* `mkws-complete.js` -- a single file consisting of `mkws.js`,
- jQuery (which it uses), Handlebars (ditto) and `pz2.js`
+* `mkws-complete.js` (and its compressed version `mkws-complete.min.js`)
+ -- a single file consisting of `mkws.js` together with the files it
+ uses: `pz2.js` jQuery, jQuery-JSON and Handlebars.
+* Local copy of `jquery-1.10.0.min.js`
+* Local copy of `jquery.json-2.4.js`
+* Local copy of `handlebars-v1.1.2.js`
* `mkws.css`
* `<div id="mkwsStat"></div>` -- summary statistics
You can configure and control the client by creating an `mkws_config`
-object _before_ loading the widget-set. Here is an example of all
-possible options:
+object before loading the widget-set. Here is an example showing how
+to use options to offer a choice between English and German UI
+languages, and to default to sorting by title ascending:
~~~
<script type="text/javascript">
var mkws_config = {
- use_service_proxy: true, /* true, flase: use service proxy instead pazpar2 */
- show_lang: true, /* true, false: show/hide language menu */
- show_sort: true, /* true, false: show/hide sort menu */
- show_perpage: true, /* true, false: show/hide perpage menu */
- show_switch: true, /* true, false: show/hide switch menu */
- lang_options: ["en", "de", "da"],
- /* display languages links for given languages, [] for all */
- facets: ["xtargets", "subject", "author"],
- /* display facets, in this order, [] for none */
- sort_default: "relevance", /* "relevance", "title:1", "date:0", "date:1" */
- query_width: 50, /* 5..50 */
- perpage_default: 20, /* 10, 20, 30, 50 */
- lang: "en", /* "en", "de", "da" */
- debug_level: 0, /* debug level for development: 0..2 */
-
- responsive_design_wodth: 600, /* page reflows for devices < 600 pixels wide */
- pazpar2_url: "/service-proxy/", /* URL */
- service_proxy_auth: "/service-proxy-auth", /* URL */
- // TODO: language_*, perpage_options, sort_options
+ lang_options: ["en", "de" ],
+ sort_default: "title:1"
};
</script>
~~~
=====================
-MKWS accesses targets using the Pazpar2 metasearching engine, almost
-always fronted by the Service Proxy to manage target selection. This
-document assumes the SP is used, and so that a library of targets is
-available, maintained using an instance of MKAdmin (often
-http://mkc-admin.indexdata.com/console/)
-
-
-1. Selecting targets within 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
+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.
+
+
+1. 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 "MKC Admin" installation at
+ http://mkx-admin.indexdata.com/console/
+
+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. Note that IT IS THEN CRUICIAL 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.
2. Authenticating onto the library
target selection within the set that it makes available can be done
using the mechanisms above.
+
+3. 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
+
+
body {
- font-family: Times, "Times Roman", "Times New Roman";
+ font-family: Baskerville, "Baskervald ADF Std", "Times New Roman", "Times Roman", Times;
}
h1, h2, h3, h4 {
<script type="text/javascript">
var mkws_config = {
pazpar2_url: "//sp-mkws.indexdata.com/service-proxy/",
- service_proxy_auth: "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=orex&password=orexmkc"
+ service_proxy_auth: "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=Xorex&password=orexmkc"
};
</script>
<script type="text/javascript" src="//code.jquery.com/jquery-1.10.0.min.js"></script>
mkws-html-includes:
echo $(COMPONENTS) | perl -npe "s,${SRC},,g; s/\s+/\0/g" | \
- perl -n0e 'print qq{ <script type="text/javascript" src="src$$_"></script>\n}'
+ perl -n0e 'chomp(); print qq{ <script type="text/javascript" src="src$$_"></script>\n}'
distclean: clean
@echo "(No need for distclean, 'make clean' is fine)"
# authn plugin, for torus based authentication
authn.TORUS_URL = http://mkc-admin.indexdata.com/torus2/identity.USERS/records/
authn.MASTER_TORUS_URL = http://mkc-admin.indexdata.com/torus2/admin.admin/records/
-authn.ACTION_SEQUENCE = check,login,ipauth,referrer
-#authn.SPECIFIC_CONSTRAINT = vhost=${thisHost}
+authn.ACTION_SEQUENCE = check,login,referrer,constraint
+authn.SPECIFIC_CONSTRAINT = hostName=${thisHost}
# categories plugin, for Torus-based target categories
categories.TORUS_BASEURL = http://mkc-admin.indexdata.com/torus2/
projects / mkws-moved-to-github.git / commitdiff