-whatevs.
+% 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 `<div>`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:
+
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>MKWS demo client</title>
+ <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
+ <link rel="stylesheet" href="http://mkws.indexdata.com/mkwsStyle.css" />
+ </head>
+ <body>
+ <div id="mkwsSearch"></div>
+ <div id="mkwsResults"></div>
+ </body>
+ </html>
+
+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 `<html>` element at the top level contains a `<head>` and a
+`<body>`. 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 `<div>` 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 `<div>`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
+`<body>` like so:
+
+ <div id="mkwsSwitch"></div>
+ <div id="mkwsLang"></div>
+ <div id="mkwsSearch"></div>
+ <div id="mkwsResults"></div>
+ <div id="mkwsTargets"></div>
+ <div id="mkwsStat"></div>
+
+Configuration
+-------------
+
+TODO
+
+resposive resize
+
+
+Control over HTML and CSS
+-------------------------
+
+TODO
+
+More sophisticated applications will not simply place the `<div>`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, <http://www.indexdata.com>
projects / mkws-moved-to-github.git / blobdiff