doc/index.markdown

   1 % MKWS: the MasterKey Widget Set
   2 % Mike Taylor
   3 % October 2014
   4
   5
   6 Add metasearching to your web-site painlessly
   7 ---------------------------------------------
   8
   9 The MasterKey Widget Set provides the easiest possible way to enhance
  10 an existing web-site with customised searching across multiple
  11 sources, ranking and merging the results.
  12
  13 As much of the searching functionality as possible is hosted on
  14 `http://mkws.indexdata.com/` so that very simple applications such as
  15 <http://example.indexdata.com/simple.html> can have MasterKey
  16 searching with minimal effort.  All you need to do is pull in our
  17 JavaScript and optional stylesheet, then add `<div>`s to your page
  18 that have special `class` attributes. We do the rest.
  19
  20 Supported Browsers
  21 ------------------
  22
  23 Any modern browser will work fine. JavaScript must be enabled.
  24
  25 * IE8 or later
  26 * Firefox 17 or later
  27 * Google Chrome 27 or later
  28 * Safari 6 or later
  29 * Opera  12 or later
  30 * iOS 6.x (iPhone, iPad)
  31 * Android 4.x
  32
  33 Not supported: IE6, IE7
  34
  35 A minimal example
  36 -----------------
  37
  38 Here is a completely functional (though ugly) MKWS-based
  39 searching application [[link]](http://example.indexdata.com/minimal.html)
  40
  41         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  42         <div class="mkwsSearch"></div>
  43         <div class="mkwsResults"></div>
  44
  45 That's it. A complete metasearching application. Everything
  46 else is refinement.
  47
  48 Configuring a client (short version)
  49 ------------------------------------
  50
  51 The application's HTML must contain the following elements as well as
  52 whatever makes up the application itself:
  53
  54         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  55         <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
  56
  57 These lines pull in JavaScript code and the default styles. (The
  58 latter may be omitted or replaced with application-specific styles for
  59 the widgets.)
  60
  61 Then the following special `<div>`s can be added (with no content), and
  62 will be filled in by MKWS:
  63
  64 * `<div class="mkwsSearch"></div>` -- search box and button
  65 * `<div class="mkwsResults"></div>` -- result list, including pager/sorting
  66 * `<div class="mkwsStat"></div>` -- summary statistics
  67 * `<div class="mkwsSwitch"></div>` -- switch between record and target views
  68 * `<div class="mkwsTargets"></div>` -- target list, including status
  69 * `<div class="mkwsLang"></div>  ` -- switch between languages, e.g. English, Danish and German
  70
  71 You can configure and control the client by creating an `mkws_config`
  72 object. Here is an example showing how to use options to offer a
  73 choice between English and German UI languages, and to default to
  74 sorting by title ascending:
  75
  76         <script type="text/javascript">
  77           var mkws_config = {
  78             lang_options: ["en", "de" ],
  79             sort_default: "title:1"
  80           };
  81         </script>
  82
  83 Detailed documentation
  84 ----------------------
  85
  86 Apart from [this file](index.html) and its [PDF version](index.pdf):
  87
  88 * The [MKWS manual, including a reference section](mkws-manual.html)
  89   [[PDF version]](mkws-manual.pdf)
  90 * The [MKWS developers' guide](mkws-developer.html)
  91   [[PDF version]](mkws-developer.pdf)
  92
  93 Widget files
  94 ------------
  95
  96 Here are the files that this web-site provides:
  97
  98 * [mkws.js](mkws.js) --
  99   JavaScript code that powers the MasterKey Widget Set
 100 * [pazpar2/js/pz2.js](pazpar2/js/pz2.js) --
 101   Low-level JavaScript library for access to the MasterKey web
 102   service.
 103 * [handlebars-v2.0.0.js](handlebars-v2.0.0.js) --
 104   A local copy of
 105   [the Handlebars templating library](//handlebarsjs.com/),
 106   since it doesn't like to be hotlinked.
 107 * Local copy of [jquery-1.10.0.min.js](jquery-1.10.0.min.js)
 108 * Local copy of [jquery.json-2.4.js](jquery.json-2.4.js)
 109 * [mkws-complete.js](mkws-complete.js) --
 110   A single large JavaScript file containing everything needed for
 111   MKWS to work: the widget-set itself, the API library, and
 112   the prerequisites jQuery and Handlebars.
 113 * [mkws.css](mkws.css) --
 114   A stylesheet which styles only MasterKey widgets, and does not
 115   otherwise interfere with application-site's styles.
 116
 117 Minified versions of the MKWS JavaScript files are also available:
 118
 119 * [mkws.min.js](mkws.min.js)
 120 * [mkws-complete.min.js](mkws-complete.min.js)
 121
 122 ### Specific versions
 123
 124 The links above to the various forms of the widget-set JavaScript
 125 ([mkws.js](mkws.js),
 126 [mkws-complete.js](mkws-complete.js),
 127 [mkws.min.js](mkws.min.js)
 128 and
 129 [mkws-complete.min.js](mkws-complete.min.js))
 130 are always to the current versions of those
 131 files. Applications that rely on a particular version can
 132 instead use the specific numbered versions in
 133 [the releases area](releases/),
 134 for example
 135 [releases/mkws-0.9.1.js](releases/mkws-0.9.1.js).
 136
 137 The current version number is always in
 138 [the VERSION file](VERSION).
 139
 140 Version history is in
 141 [the NEWS file](NEWS).
 142
 143 Examples using the widget-set
 144 -----------------------------
 145
 146 It's worth viewing the source of these to see how small they
 147 are and how various things are done.
 148
 149 ### Simple examples
 150
 151 * A very simple application at <http://example.indexdata.com/simple.html>
 152 * [The absolutely minimal application](//example.indexdata.com/minimal.html)
 153   listed above.
 154 * [A more detailed version](//example.indexdata.com/language.html)
 155   that contains a configuration structure instead of accepting the
 156   defaults. Includes a custom translation option to present the
 157   application in Arabic.
 158 * [A version suitable for mobile devices](//example.indexdata.com/mobile.html)
 159   with a responsive design that moves components around depending on
 160   the screen size.
 161
 162 ### Advanced examples
 163
 164 * An application that
 165   [uses lower-level MKWS components](//example.indexdata.com/lowlevel.html)
 166   rather than the all-in-one `#mkwsResults` division,
 167   allowing it to use a rather different layout.
 168 * An application that specifies how to display brief and full records
 169   [using Handlebar templates](//example.indexdata.com/templates.html).
 170   (Read about
 171   [the templating language](//handlebarsjs.com/).)
 172 * An application that
 173   [displays thumbnail images](//example.indexdata.com/images.html?q=portrait).
 174 * An application that
 175   [uses a local authentication regime](//example.indexdata.com/localauth.html)
 176   and the corresponding
 177   [Apache2 configuration stanza](//example.indexdata.com/apache-config.txt).
 178 * [A version that uses a jQuery popup](//example.indexdata.com/popup.html).
 179
 180 ### Non-standard interfaces
 181
 182 * An application that uses MKWS to
 183   [find dictionary definitions of words](//example.indexdata.com/dict.html)
 184   when you highlight them.
 185 * An application that
 186   [runs an automatic search on load](//example.indexdata.com/auto.html).
 187 * An existing web-site,
 188   [The Self-Appointed Grammar Police](//sagp.miketaylor.org.uk/)
 189   which has been fitted with an MKWS searching widget.
 190   (See also the MKWS-widget customisations in
 191   [that site's stylesheet](//sagp.miketaylor.org.uk/style.css).)
 192 * Another existing web-site,
 193   [The Zthes specifications](//zthes.z3950.org/),
 194   which has been fitted with a popup MKWS search-box.
 195
 196 Target selection
 197 ----------------
 198
 199 MKWS comes pre-configured to search in a set of a dozen or so
 200 open-access targets, as a proof of concept. But you'll want
 201 to use it to
 202 [search your own selection of targets](mkws-manual.html#mkws-target-selection)
 203 -- some open access, some subscription.
 204
 205 We can set that up for you: email us on <info@indexdata.com>.
 206
 207 - - -
 208
 209 Copyright (&copy;) 2013-2014 Index Data ApS. <http://indexdata.com>