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