doc/index.markdown

   1 % MKWS: the MasterKey Widget Set
   2 <!---% Mike Taylor
   3 % June 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 All you need to do is pull in our JavaScript and optional stylesheet,
  14 then add `<div>`s to your page that have special `class` attributes. We
  15 do the rest.
  16
  17 A minimal example
  18 -----------------
  19
  20 Here is a completely functional (though ugly) MKWS-based
  21 searching application:
  22
  23         <script type="text/javascript"
  24           src="http://mkws.indexdata.com/mkws-complete.js"></script>
  25         <div class="mkwsSearch"></div>
  26         <div class="mkwsResults"></div>
  27
  28 That's it. A complete metasearching application. Everything
  29 else is refinement.
  30
  31 Documentation
  32 -------------
  33
  34 * This file.
  35   [<a href="index.pdf">PDF version</a>]
  36 * The <a href="README.html">README</a> -- mostly technical details.
  37   [<a href="README.pdf">PDF version</a>]
  38 * The <a href="mkws-manual.html">MKWS manual, including a reference section.</a>
  39   [<a href="mkws-manual.pdf">PDF version</a>]
  40 * The <a href="mkws-developer.html">MKWS developers' guide.</a>
  41   [<a href="mkws-developer.pdf">PDF version</a>]
  42
  43 Tools
  44 -----
  45
  46 Here are the files that this web-site provides:
  47
  48 * <a href="mkws.js">mkws.js</a> --
  49   JavaScript code that powers the MasterKey Widget Set
  50 * <a href="pazpar2/js/pz2.js">pazpar2/js/pz2.js</a> --
  51   Low-level JavaScript library for access to the MasterKey web
  52   service.
  53 * <a href="handlebars-v2.0.0.js">handlebars-v2.0.0.js</a> --
  54   A local copy of
  55   <a href="http://handlebarsjs.com/">the Handlebars templating library</a>,
  56   since it doesn't like to be hotlinked.
  57 * Local copy of <a href="jquery-1.10.0.min.js">jquery-1.10.0.min.js</a>
  58 * Local copy of <a href="jquery.json-2.4.js">jquery.json-2.4.js</a>
  59 * <a href="mkws-complete.js">mkws-complete.js</a> --
  60   A single large JavaScript file containing everything needed for
  61   MKWS to work: the widget-set itself, the API library, and
  62   the prerequisites jQuery and Handlebars.
  63 * <a href="mkws.css">mkws.css</a> --
  64   A stylesheet which styles only MasterKey widgets, and does not
  65   otherwise interfere with application-site's styles.
  66 * <a href="mkws-jquery.js">mkws-jquery.js</a> --
  67   An experimental jQuery plugin that provides an MKWS-based
  68   metasearching applet.
  69
  70 Minified versions of the MKWS JavaScript files are also available:
  71
  72 * <a href="mkws.min.js">mkws.min.js</a>
  73 * <a href="mkws-complete.min.js">mkws-complete.min.js</a>
  74
  75 Versions
  76 --------
  77
  78 The links above to the various forms of the widget-set JavaScript
  79 (<a href="mkws.js">mkws.js</a>,
  80 <a href="mkws-complete.js">mkws-complete.js</a>,
  81 <a href="mkws.min.js">mkws.min.js</a>
  82 and
  83 <a href="mkws-complete.min.js">mkws-complete.min.js</a>)
  84 are always to the current versions of those
  85 files. Applications that rely on a particular version can
  86 instead use the specific numbered versions in
  87 <a href="releases/">the releases area</a>,
  88 for example
  89 <a href="releases/mkws-0.9.1.js">releases/mkws-0.9.1.js</a>.
  90
  91 The current version number is always in
  92 <a href="VERSION">the VERSION file</a>.
  93
  94 Version history is in
  95 <a href="NEWS">the NEWS file</a>.
  96
  97 Examples using the widget-set
  98 -----------------------------
  99
 100 It's worth viewing the source of these to see how small they
 101 are and how various things are done.
 102
 103 ### Simple examples
 104
 105 * A very simple application at
 106   <a href="//example.indexdata.com/simple.html"
 107        >//example.indexdata.com/simple.html</a>.
 108 * <a href="//example.indexdata.com/minimal.html"
 109        >The absolutely minimal application</a>
 110   listed above.
 111 * <a href="//example.indexdata.com/language.html"
 112        >A more detailed version</a>
 113   that contains a configuration structure instead of accepting the
 114   defaults. Includes a custom translation option to present the
 115   application in Arabic.
 116 * <a href="//example.indexdata.com/mobile.html"
 117        >A version suitable for mobile devices</a>,
 118   with a responsive design that moves components around depending on
 119   the screen size.
 120
 121 ### Advanced examples
 122
 123 * An application that
 124   <a href="//example.indexdata.com/lowlevel.html"
 125        >uses lower-level MKWS components</a>
 126   rather than the all-in-one `#mkwsResults` division,
 127   allowing it to use a rather different layout.
 128 * An application that specifies how to display brief and full records
 129   <a href="//example.indexdata.com/templates.html"
 130        >using Handlebar templates</a>.
 131   (Read about
 132   <a href="http://handlebarsjs.com/"
 133        >the templating language</a>.)
 134 * An application that
 135   <a href="http://example.indexdata.com/images.html?q=portrait"
 136        >displays thumbnail images</a>.
 137 * <a href="//example.indexdata.com/localauth.html"
 138        >An application that uses a local authentication regime</a>,
 139   and the corresponding
 140   <a href="//example.indexdata.com/apache-config.txt"
 141        >Apache2 configuration stanza</a>.
 142 * <a href="//example.indexdata.com/popup.html"
 143        >A version that uses a jQuery popup</a>.
 144
 145 ### Non-standard interfaces
 146
 147 * <a href="//example.indexdata.com/dict.html"
 148        >An application that uses MKWS to find dictionary
 149   definitions of words when you highlight them</a>.
 150 * <a href="//example.indexdata.com/auto.html"
 151        >An application that runs an automatic search on load</a>.
 152 * An existing web-site,
 153   <a href="http://sagp.miketaylor.org.uk/"
 154        >The Self-Appointed Grammar Police</a>,
 155   which has been fitted with an MKWS searching widget.
 156   (See also the MKWS-widget customisations in
 157   <a href="http://sagp.miketaylor.org.uk/style.css"
 158        >that site's stylesheet</a>.)
 159 <!---
 160 * Another existing web-site,
 161   <a href="http://zthes.z3950.org/"
 162        >The Zthes specifications</a>,
 163   which has been fitted with a popup MKWS search-box.
 164 -->
 165
 166 Target selection
 167 ----------------
 168
 169 MKWS comes pre-configured to search in a set of a dozen or so
 170 open-access targets, as a proof of concept. But you'll want
 171 to use it to search your own selection of targets -- some open
 172 access, some subscription.
 173
 174 We can set that up for you: email us on
 175 <a href="mailto:info@indexdata.com"
 176                >info@indexdata.com</a>.
 177
 178 - - -
 179
 180 Copyright (&copy;) 2013-2014 Index Data ApS.
 181 <a href="http://indexdata.com">`http://indexdata.com`</a>