doc/README.markdown

   1 % The MasterKey Widget Set
   2 % Mike Taylor; Wolfram Schneider
   3 % 10 July 2014
   4
   5
   6 Introduction
   7 ------------
   8
   9 This is the MasterKey Widget Set. It provides searching and other
  10 information-related functionality which can be inserted into existing
  11 web pages as small snippets of HTML.
  12
  13 As much of the searching functionality as possible is hosted on
  14         <http://mkws.indexdata.com/>
  15 so that very simple websites such as
  16         <http://example.indexdata.com/>
  17 can have MasterKey searching with minimal effort.
  18
  19 The following files are hosted on `mkws.indexdata.com`:
  20
  21 * `mkws.js` (and its compressed version `mkws.min.js`)
  22 * `/pazpar2/js/pz2.js`
  23 * `mkws-complete.js` (and its compressed version `mkws-complete.min.js`)
  24   -- a single file consisting of `mkws.js` together with the files it
  25   uses: `pz2.js` jQuery, jQuery-JSON and Handlebars.
  26 * Local copy of `jquery-1.10.0.min.js`
  27 * Local copy of `jquery.json-2.4.js`
  28 * Local copy of `handlebars-v1.1.2.js`
  29 * `mkws.css`
  30
  31
  32 Supported Browsers
  33 ------------------
  34
  35 Any modern browser will work fine. JavaScript must be enabled.
  36
  37 * IE8 or later
  38 * Firefox 17 or later
  39 * Google Chrome 27 or later
  40 * Safari 6 or later
  41 * Opera  12 or later
  42 * iOS 6.x (iPhone, iPad)
  43 * Android 4.x
  44
  45 Not supported: IE6, IE7
  46
  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 of all
  73 possible options:
  74
  75 ~~~
  76     <script type="text/javascript">
  77       var mkws_config = {
  78         use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
  79         show_lang: true,            /* true, false: show/hide language menu */
  80         show_sort: true,            /* true, false: show/hide sort menu */
  81         show_perpage: true,         /* true, false: show/hide perpage menu */
  82         show_switch: true,          /* true, false: show/hide switch menu */
  83         lang_options: ["en", "de", "da"],
  84                                     /* display languages links for given languages, [] for all */
  85         facets: ["xtargets", "subject", "author"],
  86                                     /* display facets, in this order, [] for none */
  87         sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
  88         query_width: 50,            /* 5..50 */
  89         perpage_default: 20,        /* 10, 20, 30, 50 */
  90         lang: "en",                 /* "en", "de", "da" */
  91         debug_level: 0,             /* debug level for development: 0..2 */
  92
  93         responsive_design_wodth: 600,    /* page reflows for devices < 600 pixels wide */
  94         pazpar2_url: "/service-proxy/",            /* URL */
  95         service_proxy_auth: "/service-proxy-auth", /* URL */
  96         // TODO: language_*, perpage_options, sort_options
  97       };
  98     </script>
  99 ~~~
 100
 101 For much more detail, see
 102 [the MKWS whitepaper](whitepaper.html).
 103
 104
 105 - - -
 106
 107 Copyright 2014 IndexData ApS. <http://indexdata.com>