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 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:
  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 contains the following elements as well as
  52 whatever makes up the application itself:
  53
  54 Prerequisites:
  55
  56 ~~~
  57         <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
  58         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  59 ~~~
  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 id="mkwsSwitch"></div>` -- switch between record and target views
  65 * `<div id="mkwsLang"></div>  ` -- switch between English, Danish and German
  66 * `<div id="mkwsSearch"></div>` -- search box and button
  67 * `<div id="mkwsResults"></div>` -- result list, including pager/sorting
  68 * `<div id="mkwsTargets"></div>` -- target list, including status
  69 * `<div id="mkwsStat"></div>` -- summary statistics
  70
  71 You can configure and control the client by creating an `mkws_config`
  72 object before loading the widget-set. Here is an example showing how
  73 to use options to offer a choice between English and German UI
  74 languages, and to default to sorting by title ascending:
  75
  76 ~~~
  77     <script type="text/javascript">
  78       var mkws_config = {
  79         lang_options: ["en", "de" ],
  80         sort_default: "title:1"
  81       };
  82     </script>
  83 ~~~
  84
  85 For much more detail, see:
  86 [Embedded metasearching with the MasterKey Widget Set](mkws-manual.html)
  87
  88 Documentation
  89 -------------
  90
  91 * This file.
  92   [<a href="index.pdf">PDF version</a>]
  93 * The <a href="README.html">README</a> -- mostly technical details.
  94   [<a href="README.pdf">PDF version</a>]
  95 * The <a href="mkws-manual.html">MKWS manual, including a reference section.</a>
  96   [<a href="mkws-manual.pdf">PDF version</a>]
  97 * The <a href="mkws-developer.html">MKWS developers' guide.</a>
  98   [<a href="mkws-developer.pdf">PDF version</a>]
  99
 100 Tools
 101 -----
 102
 103 Here are the files that this web-site provides:
 104
 105 * <a href="mkws.js">mkws.js</a> --
 106   JavaScript code that powers the MasterKey Widget Set
 107 * <a href="pazpar2/js/pz2.js">pazpar2/js/pz2.js</a> --
 108   Low-level JavaScript library for access to the MasterKey web
 109   service.
 110 * <a href="handlebars-v2.0.0.js">handlebars-v2.0.0.js</a> --
 111   A local copy of
 112   <a href="http://handlebarsjs.com/">the Handlebars templating library</a>,
 113   since it doesn't like to be hotlinked.
 114 * Local copy of <a href="jquery-1.10.0.min.js">jquery-1.10.0.min.js</a>
 115 * Local copy of <a href="jquery.json-2.4.js">jquery.json-2.4.js</a>
 116 * <a href="mkws-complete.js">mkws-complete.js</a> --
 117   A single large JavaScript file containing everything needed for
 118   MKWS to work: the widget-set itself, the API library, and
 119   the prerequisites jQuery and Handlebars.
 120 * <a href="mkws.css">mkws.css</a> --
 121   A stylesheet which styles only MasterKey widgets, and does not
 122   otherwise interfere with application-site's styles.
 123 * <a href="mkws-jquery.js">mkws-jquery.js</a> --
 124   An experimental jQuery plugin that provides an MKWS-based
 125   metasearching applet.
 126
 127 Minified versions of the MKWS JavaScript files are also available:
 128
 129 * <a href="mkws.min.js">mkws.min.js</a>
 130 * <a href="mkws-complete.min.js">mkws-complete.min.js</a>
 131
 132 ### Specific versions
 133
 134 The links above to the various forms of the widget-set JavaScript
 135 (<a href="mkws.js">mkws.js</a>,
 136 <a href="mkws-complete.js">mkws-complete.js</a>,
 137 <a href="mkws.min.js">mkws.min.js</a>
 138 and
 139 <a href="mkws-complete.min.js">mkws-complete.min.js</a>)
 140 are always to the current versions of those
 141 files. Applications that rely on a particular version can
 142 instead use the specific numbered versions in
 143 <a href="releases/">the releases area</a>,
 144 for example
 145 <a href="releases/mkws-0.9.1.js">releases/mkws-0.9.1.js</a>.
 146
 147 The current version number is always in
 148 <a href="VERSION">the VERSION file</a>.
 149
 150 Version history is in
 151 <a href="NEWS">the NEWS file</a>.
 152
 153 Examples using the widget-set
 154 -----------------------------
 155
 156 It's worth viewing the source of these to see how small they
 157 are and how various things are done.
 158
 159 ### Simple examples
 160
 161 * A very simple application at
 162   <a href="//example.indexdata.com/simple.html"
 163        >//example.indexdata.com/simple.html</a>.
 164 * <a href="//example.indexdata.com/minimal.html"
 165        >The absolutely minimal application</a>
 166   listed above.
 167 * <a href="//example.indexdata.com/language.html"
 168        >A more detailed version</a>
 169   that contains a configuration structure instead of accepting the
 170   defaults. Includes a custom translation option to present the
 171   application in Arabic.
 172 * <a href="//example.indexdata.com/mobile.html"
 173        >A version suitable for mobile devices</a>,
 174   with a responsive design that moves components around depending on
 175   the screen size.
 176
 177 ### Advanced examples
 178
 179 * An application that
 180   <a href="//example.indexdata.com/lowlevel.html"
 181        >uses lower-level MKWS components</a>
 182   rather than the all-in-one `#mkwsResults` division,
 183   allowing it to use a rather different layout.
 184 * An application that specifies how to display brief and full records
 185   <a href="//example.indexdata.com/templates.html"
 186        >using Handlebar templates</a>.
 187   (Read about
 188   <a href="http://handlebarsjs.com/"
 189        >the templating language</a>.)
 190 * An application that
 191   <a href="http://example.indexdata.com/images.html?q=portrait"
 192        >displays thumbnail images</a>.
 193 * <a href="//example.indexdata.com/localauth.html"
 194        >An application that uses a local authentication regime</a>,
 195   and the corresponding
 196   <a href="//example.indexdata.com/apache-config.txt"
 197        >Apache2 configuration stanza</a>.
 198 * <a href="//example.indexdata.com/popup.html"
 199        >A version that uses a jQuery popup</a>.
 200
 201 ### Non-standard interfaces
 202
 203 * <a href="//example.indexdata.com/dict.html"
 204        >An application that uses MKWS to find dictionary
 205   definitions of words when you highlight them</a>.
 206 * <a href="//example.indexdata.com/auto.html"
 207        >An application that runs an automatic search on load</a>.
 208 * An existing web-site,
 209   <a href="http://sagp.miketaylor.org.uk/"
 210        >The Self-Appointed Grammar Police</a>,
 211   which has been fitted with an MKWS searching widget.
 212   (See also the MKWS-widget customisations in
 213   <a href="http://sagp.miketaylor.org.uk/style.css"
 214        >that site's stylesheet</a>.)
 215 <!---
 216 * Another existing web-site,
 217   <a href="http://zthes.z3950.org/"
 218        >The Zthes specifications</a>,
 219   which has been fitted with a popup MKWS search-box.
 220 -->
 221
 222 Target selection
 223 ----------------
 224
 225 MKWS comes pre-configured to search in a set of a dozen or so
 226 open-access targets, as a proof of concept. But you'll want
 227 to use it to search your own selection of targets -- some open
 228 access, some subscription.
 229
 230 We can set that up for you: email us on
 231 <a href="mailto:info@indexdata.com"
 232                >info@indexdata.com</a>.
 233
 234 - - -
 235
 236 Copyright (&copy;) 2013-2014 Index Data ApS.
 237 <a href="http://indexdata.com">`http://indexdata.com`</a>