tools/htdocs/README.markdown

   1 % The MasterKey Widget Set
   2 % Mike Taylor; Wolfram Schneider
   3 % 10 July 2013
   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`
  22 * `/pazpar2/js/pz2.js`
  23 * `mkws-complete.js` -- a single file consisting of `mkws.js`,
  24   jQuery (which it uses), Handlebars (ditto) and `pz2.js`
  25 * `mkws.css`
  26
  27
  28 Supported Browsers
  29 ------------------
  30
  31 Any modern browser will work fine. JavaScript must be enabled.
  32
  33 * IE8 or later
  34 * Firefox 17 or later
  35 * Google Chrome 27 or later
  36 * Safari 6 or later
  37 * Opera  12 or later
  38 * iOS 6.x (iPhone, iPad)
  39 * Android 4.x
  40
  41 Not supported: IE6, IE7
  42
  43
  44 Configuring a client
  45 --------------------
  46
  47 The application's HTML must contains the following elements as well as
  48 whatever makes up the application itself:
  49
  50 Prerequisites:
  51
  52 ~~~
  53         <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
  54         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  55 ~~~
  56
  57 Then the following special `<div>`s can be added (with no content), and
  58 will be filled in by MKWS:
  59
  60 * `<div id="mkwsSwitch"></div>` -- switch between record and target views
  61 * `<div id="mkwsLang"></div>  ` -- switch between English, Danish and German
  62 * `<div id="mkwsSearch"></div>` -- search box and button
  63 * `<div id="mkwsResults"></div>` -- result list, including pager/sorting
  64 * `<div id="mkwsTargets"></div>` -- target list, including status
  65 * `<div id="mkwsStat"></div>` -- summary statistics
  66
  67 You can configure and control the client by creating an `mkws_config`
  68 object _before_ loading the widget-set.  Here is an example of all
  69 possible options:
  70
  71 ~~~
  72     <script type="text/javascript">
  73       var mkws_config = {
  74         use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
  75         show_lang: true,            /* true, false: show/hide language menu */
  76         show_sort: true,            /* true, false: show/hide sort menu */
  77         show_perpage: true,         /* true, false: show/hide perpage menu */
  78         lang_options: ["en", "de", "da"],
  79                                     /* display languages links for given languages, [] for all */
  80         facets: ["sources", "subjects", "authors"],
  81                                     /* display facets, in this order, [] for none */
  82         sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
  83         query_width: 50,            /* 5..50 */
  84         perpage_default: 20,        /* 10, 20, 30, 50 */
  85         lang: "en",                 /* "en", "de", "da" */
  86         debug_level: 0,             /* debug level for development: 0..2 */
  87
  88         responsive_design_wodth: 600,    /* page reflows for devices < 600 pixels wide */
  89         pazpar2_url: "/service-proxy/",            /* URL */
  90         service_proxy_auth: "/service-proxy-auth", /* URL */
  91         // TODO: language_*, perpage_options, sort_options
  92       };
  93     </script>
  94 ~~~
  95
  96 For much more detail, see
  97 [the MKWS whitepaper](whitepaper.html).
  98
  99
 100 - - -
 101
 102 Copyright 2013 IndexData ApS. <http://indexdata.com>