tools/htdocs/whitepaper.markdown

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