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. The initial version was based on the
  10 "jsdemo" application distributed with pazpar2, but it is now far
  11 removed from those beginnnings.
  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>