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