tools/htdocs/whitepaper.markdown

   1 % Embedded metasearching with the MasterKey Widget Set
   2 % Mike Taylor
   3 % 26 July 2013
   4
   5
   6 Introduction
   7 ------------
   8
   9 There are lots of practical problems in building resource discovery
  10 solutions. One of the biggest, and most ubiquitous is incorporating
  11 metasearching functionality into existing web-sites -- for example,
  12 content-management systems, library catalogues or intranets. In
  13 general, even when access to metasearching is provided by simple
  14 web-services such as [Pazpar2](http://www.indexdata.com/pazpar2),
  15 integration work is seen as a major part of most projects.
  16
  17 Index Data provides several different toolkits for communicating with
  18 its metasearching middleware, trading off varying degrees of
  19 flexibility against convenience:
  20
  21 * libpz2.js -- a low-level JavaScript library for interrogating the
  22   Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer
  23   to implement simple JavaScript functions to display facets, records,
  24   etc.
  25
  26 * masterkey-ui-core -- a higher-level, complex JavaScript library that
  27   uses libpz2.js to provide the pieces needed for building a
  28   full-featured JavaScript application.
  29
  30 * MasterKey Demo UI -- an example of a searching application built on
  31   top of masterkey-ui-core. Available as a public demo at
  32   http://mk2.indexdata.com/
  33
  34 * MKDru -- a toolkit for embedding MasterKey-like searching into
  35   Drupal sites.
  36
  37 All of these approaches require programming to a greater or lesser
  38 extent. Against this backdrop, we introduced MKWS (the MasterKey
  39 Widget Set) -- a set of simple, very high-level HTML+CSS+JavaScript
  40 components that can be incorporated into any web-site to provide
  41 MasterKey searching facilities. By placing `<div>`s with well-known
  42 identifiers in any HTML page, the various components of an application
  43 can be embedded: search-boxes, results areas, target information, etc.
  44
  45
  46 Simple Example
  47 --------------
  48
  49 The following is a complete MKWS-based searching application:
  50
  51     <html>
  52       <head>
  53         <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  54         <title>MKWS demo client</title>
  55         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  56         <link rel="stylesheet" href="http://mkws.indexdata.com/mkwsStyle.css" />
  57       </head>
  58       <body>
  59         <div id="mkwsSearch"></div>
  60         <div id="mkwsResults"></div>
  61       </body>
  62     </html>
  63
  64 Go ahead, try it! You don't even need a web-server. Just copy and
  65 paste this HTML into a file on your computer -- `/tmp/magic.html`,
  66 say -- and point your web-browser at it:
  67 `file:///tmp/magic.html`. Just like that, you have working
  68 metasearching.
  69
  70
  71 How the example works
  72 ---------------------
  73
  74 If you know any HTML, the structure of the file will be familar to
  75 you: the `<html>` element at the top level contains a `<head>` and a
  76 `<body>`. In addition to whatever else you might want to put on your
  77 page, you can add MKWS elements.
  78
  79 These fall into two categories. First, the prerequisites in the HTML
  80 header, which are loaded from the tool site mkws.indexdata.com:
  81
  82 * `mkws-complete.js`
  83   contains all the JavaScript needed by the widget-set.
  84
  85 * `mkwsStyle.css`
  86   provides the default CSS styling
  87
  88 Second, the `<div>` elements with special IDs that begin `mkws` can be
  89 provided. These are filled in by the MKWS code, and provide the
  90 components of the searching UI. The very simple application above has
  91 only two such components: a search box and a results area. But more
  92 are supported. The main `<div>`s are:
  93
  94 * `mkwsSearch` -- provides the search box and button.
  95
  96 * `mkwsResults` -- provides the results area, including a list of
  97    brief records (which open out into full versions when clicked),
  98    paging for large results sets, facets for refining a search,
  99    sorting facilities, etc.
 100
 101 * `mkwsLang` -- provides links to switch between one of several
 102    different UI languages. By default, English, Danish and German are
 103    provided.
 104
 105 * `mkwsSwitch` -- provides links to switch between a view of the
 106    result records and of the targets that provide them. Only
 107    meaningful when `mkwsTargets` is also provided.
 108
 109 * `mkwsTargets` -- the area where per-target information will appear
 110    when selected by the link in the `mkwsSwitch` area. Of interest
 111    mostly for fault diagnosis rather than for end-users.
 112
 113 * `mkwsStat` --provides a status line summarising the statistics of
 114    the various targets.
 115
 116 To see all of these working together, just put them all into the HTML
 117 `<body>` like so:
 118
 119         <div id="mkwsSwitch"></div>
 120         <div id="mkwsLang"></div>
 121         <div id="mkwsSearch"></div>
 122         <div id="mkwsResults"></div>
 123         <div id="mkwsTargets"></div>
 124         <div id="mkwsStat"></div>
 125
 126 Configuration
 127 -------------
 128
 129 TODO
 130
 131 resposive resize
 132
 133
 134 Control over HTML and CSS
 135 -------------------------
 136
 137 TODO
 138
 139 More sophisticated applications will not simply place the `<div>`s
 140 together, but position them carefully within an existing page
 141 framework -- such as a Drupal template, an OPAC or a SharePoint page.
 142
 143 Breaking up mkwsResults
 144
 145 overriding styles
 146
 147
 148 Popup results with jQuery UI
 149 ----------------------------
 150
 151 TODO
 152
 153
 154 Authentication and target configuration
 155 ---------------------------------------
 156
 157 TODO
 158
 159
 160 Reference Guide
 161 ---------------
 162
 163 ### Configuration object
 164
 165 TODO
 166
 167 ### jQuery plugin invocation
 168
 169 TODO
 170
 171 ### The structure of the HTML generated by the MKWS widgets
 172
 173 TODO
 174
 175 - - -
 176
 177 Copyright (C) 2013 by IndexData ApS, <http://www.indexdata.com>