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