% Embedded metasearching with the MasterKey Widget Set
% Mike Taylor
% 26 July 2013
Introduction
------------
There are lots of practical problems in building resource discovery
solutions. One of the biggest, and most ubiquitous is incorporating
metasearching functionality into existing web-sites -- for example,
content-management systems, library catalogues or intranets. In
general, even when access to metasearching is provided by simple
web-services such as [Pazpar2](http://www.indexdata.com/pazpar2),
integration work is seen as a major part of most projects.
Index Data provides several different toolkits for communicating with
its metasearching middleware, trading off varying degrees of
flexibility against convenience:
* libpz2.js -- a low-level JavaScript library for interrogating the
Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer
to implement simple JavaScript functions to display facets, records,
etc.
* masterkey-ui-core -- a higher-level, complex JavaScript library that
uses libpz2.js to provide the pieces needed for building a
full-featured JavaScript application.
* MasterKey Demo UI -- an example of a searching application built on
top of masterkey-ui-core. Available as a public demo at
http://mk2.indexdata.com/
* MKDru -- a toolkit for embedding MasterKey-like searching into
Drupal sites.
All of these approaches require programming to a greater or lesser
extent. Against this backdrop, we introduced MKWS (the MasterKey
Widget Set) -- a set of simple, very high-level HTML+CSS+JavaScript
components that can be incorporated into any web-site to provide
MasterKey searching facilities. By placing `
`s with well-known
identifiers in any HTML page, the various components of an application
can be embedded: search-boxes, results areas, target information, etc.
Simple Example
--------------
The following is a complete MKWS-based searching application:
MKWS demo client
Go ahead, try it! You don't even need a web-server. Just copy and
paste this HTML into a file on your computer -- `/tmp/magic.html`,
say -- and point your web-browser at it:
`file:///tmp/magic.html`. Just like that, you have working
metasearching.
How the example works
---------------------
If you know any HTML, the structure of the file will be familar to
you: the `` element at the top level contains a `` and a
``. In addition to whatever else you might want to put on your
page, you can add MKWS elements.
These fall into two categories. First, the prerequisites in the HTML
header, which are loaded from the tool site mkws.indexdata.com:
* `mkws-complete.js`
contains all the JavaScript needed by the widget-set.
* `mkwsStyle.css`
provides the default CSS styling
Second, the `
` elements with special IDs that begin `mkws` can be
provided. These are filled in by the MKWS code, and provide the
components of the searching UI. The very simple application above has
only two such components: a search box and a results area. But more
are supported. The main `
`s are:
* `mkwsSearch` -- provides the search box and button.
* `mkwsResults` -- provides the results area, including a list of
brief records (which open out into full versions when clicked),
paging for large results sets, facets for refining a search,
sorting facilities, etc.
* `mkwsLang` -- provides links to switch between one of several
different UI languages. By default, English, Danish and German are
provided.
* `mkwsSwitch` -- provides links to switch between a view of the
result records and of the targets that provide them. Only
meaningful when `mkwsTargets` is also provided.
* `mkwsTargets` -- the area where per-target information will appear
when selected by the link in the `mkwsSwitch` area. Of interest
mostly for fault diagnosis rather than for end-users.
* `mkwsStat` --provides a status line summarising the statistics of
the various targets.
To see all of these working together, just put them all into the HTML
`` like so:
Configuration
-------------
TODO
resposive resize
Control over HTML and CSS
-------------------------
TODO
More sophisticated applications will not simply place the `
`s
together, but position them carefully within an existing page
framework -- such as a Drupal template, an OPAC or a SharePoint page.
Breaking up mkwsResults
overriding styles
Popup results with jQuery UI
----------------------------
TODO
Authentication and target configuration
---------------------------------------
TODO
Reference Guide
---------------
### Configuration object
TODO
### jQuery plugin invocation
TODO
### The structure of the HTML generated by the MKWS widgets
TODO
- - -
Copyright (C) 2013 by IndexData ApS,