The following is
[a complete MKWS-based searching application](//example.indexdata.com/simple.html):
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>MKWS demo client</title>
- <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
- <link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
- </head>
- <body>
- <div class="mkws-search"></div>
- <div class="mkws-results"></div>
- </body>
- </html>
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>MKWS demo client</title>
+ <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
+ <link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
+ </head>
+ <body>
+ <div class="mkws-search"></div>
+ <div class="mkws-results"></div>
+ </body>
+ </html>
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
To see all of these working together, just put them all into the HTML
`<body>` like so:
- <div class="mkws-switch"></div>
- <div class="mkws-lang"></div>
- <div class="mkws-progress"></div>
- <div class="mkws-search"></div>
- <div class="mkws-results"></div>
- <div class="mkws-targets"></div>
- <div class="mkws-stat"></div>
+ <div class="mkws-switch"></div>
+ <div class="mkws-lang"></div>
+ <div class="mkws-progress"></div>
+ <div class="mkws-search"></div>
+ <div class="mkws-results"></div>
+ <div class="mkws-targets"></div>
+ <div class="mkws-stat"></div>
The full set of supported widgets is described in the
-reference guide below.
+reference guide
+[below](#widgets).
Widget team
-----------
parameters into the `mkws_config` object. So the HTML header looks
like this:
- <script type="text/javascript">
- var mkws_config = {
- lang_options: [ "en", "da" ]
- lang: "da",
- sort_default: "title",
- query_width: 60
- };
- </script>
- <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
+ <script type="text/javascript">
+ var mkws_config = {
+ lang_options: [ "en", "da" ]
+ lang: "da",
+ sort_default: "title",
+ query_width: 60
+ };
+ </script>
+ <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
This configuration restricts the set of available UI languages English
and Danish (omitting German), sets the default to Danish (rather than
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.
`type="text/x-handlebars-template"` attribute. For example, to override the
pager template you would include this in your document:
- <script class="mkws-template-pager" type="text/x-handlebars-template">
- ...new Pager template
- </script>
+ <script class="mkws-template-pager" type="text/x-handlebars-template">
+ ...new Pager template
+ </script>
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.
this to work you'll need to enable verbose output from Handlebars which is done
by including this line or similar:
- <script>Handlebars.logger.level = 1;</script>
+ <script>Handlebars.logger.level = 1;</script>
Internationalisation
--------------------
the source via the address provided in the metadata as the first
element of `md-electronic-url`:
- <script class="mkws-template-summary" type="text/x-handlebars-template">
- <a href="{{md-electronic-url.[0]}}">
- <b>{{md-title}}</b>
- </a>
- {{#if md-title-remainder}}
- <span>{{md-title-remainder}}</span>
- {{/if}}
- {{#if md-title-responsibility}}
- <span><i>{{md-title-responsibility}}</i></span>
- {{/if}}
- </script>
+ <script class="mkws-template-summary" type="text/x-handlebars-template">
+ <a href="{{md-electronic-url.[0]}}">
+ <b>{{md-title}}</b>
+ </a>
+ {{#if md-title-remainder}}
+ <span>{{md-title-remainder}}</span>
+ {{/if}}
+ {{#if md-title-responsibility}}
+ <span><i>{{md-title-responsibility}}</i></span>
+ {{/if}}
+ </script>
For a more involved example where markup for multiple widgets is decorated with
[Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is
in a popup. The key part of such an application is this invocation of
the MKWS jQuery plugin:
- <div class="mkws-search"></div>
- <div class="mkws-popup" popup_width="1024" popup_height="650">
- <div class="mkws-results"></div>
- </div>
+ <div class="mkws-search"></div>
+ <div class="mkws-popup" popup_width="1024" popup_height="650">
+ <div class="mkws-results"></div>
+ </div>
The necessary scaffolding can be seen in an example application,
[popup.html](http://example.indexdata.com/popup.html).
password), it's necessary to pass these credentials into the Service
Proxy when establishing the session. This is done
by setting the `sp_auth_credentials` configuration item to a string
-containing the username, a slash, and the password:
+containing the username and password separated by a slash:
- mkws_config = { sp_auth_credentials: "mike/swordfish" };
+ 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:
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/>
+`http://yourname.com/spauth/`.
-Step 3: protect access to the local path <http://yourname.com/spauth/>
+Step 3: protect access to the local path `http://yourname.com/spauth/`
(e.g. using a `.htaccess` file).
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,
+ `<div class="mkws-cover-art" autosearch="isbn=1291177124"></div>`
+ 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
+ `<script class="mkws-template-done" type="text/x-handlebars-template">`.
+
+`facet` A facet that displays the frequency with which a set
+ of terms occur within a specific field. The specific
+ field whose contents are analysed must be specified
+ by the widget's `facet` configuration item, which
+ may conveniently be done by means of the
+ `data-mkws-facet` attribute on the HTML
+ element. The supported facets are "subject",
+ "author" and "xtargets" -- the latter a special case
+ which treats the target providing a record as a
+ facet. Most often, `facet` widgets are generated
+ by a `facets` widget, which knows which facets are
+ required, but they can also be placed individually.
+
+`facets` An area that contains a "Facets" heading and several
+ `facet` widgets. The set of facet widgets generated
+ is specified by the `facets` configuration item,
+ which may be set globally or at the level of the
+ widget or the team. The value of this configuration
+ item is an array of zero or more strings, each
+ naming a facet.
+
+`google-image` A specialisation of the `images` widget which
+ defaults to the `Google_Images` target.
+
+`images` A specialisation of the `records` widget which
+ defaults to the `images` template. Unlike the default
+ summary template, this displays an image from the
+ URL specified by the `md-thumburl` field of each
+ record.
+
+`lang` Provides a selection between the supported set of
+ languages (which defaults to English, German and
+ Danish, but can be configured by the `lang`
+ configuration item, whose value is an array of
+ two-letter language codes).
+
+`log` Initially empty, this widget accumulates a log of
+ messages generated by the widget set, similar to
+ those emitted on the JavaScript console.
+
+`lolcat` A specialisation of the `google-image` widget which
+ defaults to the search-term "kitteh" and
+ auto-executes.
+
+`motd-container` An empty container which the `motd` widget, if any,
+ is moved into for initial display. Usually generated
+ as part of the `results` widget.
+
+`motd` May be provided, containing content to appear in the
+ area where records will later appear. It is moved
+ into this area (the `motd-container` widget) and
+ initially displayed; then hidden when the first
+ search is run. It can be used to provide a "message
+ of the day".
+
+`navi` Shows a list of the facets that have been selected,
+ and allows them to be deselected.
+
+`pager` Shows a list of the available pages of results, and
+ allows the user to navigate to a selected page.
+
+`per-page` Provides a dropdown allowing the user to choose how
+ many records should appear on each page. The
+ available set of page-sizes can be set as the
+ `perpage_options` configuration item, whose value is
+ an array of integers. The initial selected value can
+ be set by the `perpage_default` configuration item.
+
+`progress` Shows a progress bar which indicates how many of the
+ targets have responded to the search.
+
+`query` The input area for a query. Usually generated a `search`
+ widget.
+
+`ranking` The result-ranking area, consisting of a `sort`
+ widget and a `per-page` widget. These may instead
+ be specified separately if preferred.
+
+`record` A detailed display of a single record, usually
+ appearing when the user clicks on a summary
+ record. This is generated by the `records` widget.
+
+`records` The area in which summary records appear. (Clicking
+ on a summary record make it pop up as a detailed
+ record.)
+
+`reference` A short summary about a subject specified by the
+ `autosearch` configuration item. This is created by
+ drawing a picture and a paragraph of text from
+ Wikipedia. To work correctly, this widget must be
+ used in a library that provides the
+ `wikimedia_wikipedia_single_result` target.
+
+`results` A large compound widget used to provide the most
+ important results-oriented widgets in a pre-packaged
+ framework: `facets`, `ranking`, `pager`, `navi` and
+ `records`.
+
+`search-form` The search form, containing the query area and the
+ button. Usually generated a `search` widget.
+
+`search` The search box, consisting of a form containing a
+ query area and a button.
+
+`sort` Provides a dropdown allowing the user to choose how
+ the displayed records should be sorted. The
+ available set of sort criteria can be set as the
+ `sort_options` configuration item, whose value is
+ an array of two-element arrays. The first item of
+ each sub-array is a pazpar2 sort-expression such as
+ `data:0` and the second is a human-readable label
+ such as `newest`. The initial selected
+ value can be set by the `sort_default` configuration
+ item.
+
+`stat` A summary line stating how many targets remain
+ active, how many records have been found, and how
+ many of them have been retrieved for display. For
+ most purposes, the `progress` widget may be
+ preferable.
+
+`summary` A short record, included in the list shown when a
+ search is run. When clicked, this generally pops up
+ a detailed `record` widget. This widget is generated
+ by the toolkit in response to search results.
+
+`switch` A pair of buttons allowing the user to switch
+ between viewing the search results (the usual case)
+ or the target list.
+
+`targets` A list of all targets in the present library,
+ showing their ID, the number of records they have
+ found for the current search, any diagnostics they
+ have returned, the number of records that have been
+ returned for display, and the connection state.
+----
+
+
Configuration object
--------------------
----
Element Type Default Description
-------- ----- --------- ------------
-log_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
- datestamps, 3 = messages with datestamps and stack-traces.
+auth_hostname
+
+autosearch
+
+facet
+
+facet_caption_*
+
+facet_max_*
facets array *Note 1* Ordered list of names of facets to display. Supported facet names are
`xtargets`, `subject` and `author`.
`language_` followed by the code of the language. See the separate section below for
details.
+limit
+
+log_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
+ datestamps, 3 = messages with datestamps and stack-traces.
+
+maxrecs
+
+paragraphs
+
pazpar2_url string *Note 2* The URL used to access the metasearch middleware. This service must be configured to
provide search results, facets, etc. It may be either unmediated or Pazpar2 the
MasterKey Service Proxy, which mediates access to an underlying Pazpar2 instance. In
the latter case, `service_proxy_auth` must be provided.
+perpage
+
perpage_default string 20 The initial value for the number of records to show on each page.
perpage_options array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many
records are displayed on each page of results.
+pp2_hostname
+
+pp2_path
+
+query
+
query_width int 50 The width of the query box, in characters.
responsive_design_width int If defined, then the facets display moves between two locations as the screen-width
varies, as described above. The specified number is the threshhold width, in pixels,
at which the facets move between their two locations.
+scan_all_nodes
+
+sentences
+
service_proxy_auth url *Note 4* A URL which, when `use_service_proxy` is true, is fetched once at the beginning of each
session to authenticate the user and establish a session that encompasses a defined set
of targets to search in.
show_switch bool true Indicates whether or not to display the switch menu, for switching between showing
retrieved records and target information.
+sort
+
sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort`
array.
the first element of each sublist is a pazpar2 sort-expression such as `data:0` and
the second is a human-readable label such as `newest`.
+sp_auth_credentials
+
+sp_auth_path
+
+sp_auth_query
+
+target
+
+targetfilter
+
+targets
+
+template
+
+text
+
use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw
Pazpar2.
----
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`,
`Search`,
`Sort by`,
`Targets`,
-`Termlists`,
+`Facets`,
`and show`,
`found`,
`of`,
toolkit are used, so it's necessary to include both CSS and JavaScript
from that toolkit. The relevant lines are:
- <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
- <link rel="stylesheet" type="text/css"
- href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
+ <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
+ <link rel="stylesheet" type="text/css"
+ href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
- <div class="mkws-search"></div>
- <div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
- <div class="mkws-switch"></div>
- <div class="mkws-lang"></div>
- <div class="mkws-results"></div>
- <div class="mkws-targets"></div>
- <div class="mkws-stat"></div>
- </div>
+ <div class="mkws-search"></div>
+ <div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
+ <div class="mkws-switch"></div>
+ <div class="mkws-lang"></div>
+ <div class="mkws-results"></div>
+ <div class="mkws-targets"></div>
+ <div class="mkws-stat"></div>
+ </div>
----
Element Type Default Description
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 `<div>` 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
- - -
projects / mkws-moved-to-github.git / blobdiff