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 Configuring a client
  29 --------------------
  30
  31 The application's HTML must contains the following elements as well as
  32 whatever makes up the application itself:
  33
  34 Prerequisites:
  35
  36 ~~~
  37         <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
  38         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
  39 ~~~
  40
  41 Then the following special `<div>`s can be added (with no content), and
  42 will be filled in by MKWS:
  43
  44 * `<div id="mkwsSwitch"></div>` -- switch between record and target views
  45 * `<div id="mkwsLang"></div>  ` -- switch between English, Danish and German
  46 * `<div id="mkwsSearch"></div>` -- search box and button
  47 * `<div id="mkwsResults"></div>` -- result list, including pager/sorting
  48 * `<div id="mkwsTargets"></div>` -- target list, including status
  49 * `<div id="mkwsStat"></div>` -- summary statistics
  50
  51 At present, MKWS may not work correctly if some of these are
  52 missing. One of the TODOs is to fix it so that it doesn't try to use
  53 whatever is not there, and just uses what is.
  54
  55 You can configure and control the client by creating an `mkws_config`
  56 object _before_ loading the widget-set.  Here is an example of all
  57 possible options:
  58
  59 ~~~
  60         <script type="text/javascript">
  61             var mkws_config = {
  62                 use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
  63                 show_lang: true,            /* true, false: show/hide language menu */
  64                 show_sort: true,            /* true, false: show/hide sort menu */
  65                 show_perpage: true,         /* true, false: show/hide perpage menu */
  66                 lang_options: ["en", "de", "da"], /* display languages links for given
  67                                                      languages, [] for all */
  68                 facets: ["sources", "subjects", "authors"], /* display facets, in this order, [] for none */
  69                 sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
  70                 query_width: 50,            /* 5..50 */
  71                 perpage_default: 20,        /* 10, 20, 30, 50 */
  72                 lang: "en",                 /* "en", "de", "da" */
  73                 debug_level: 0,         /* debug level for development: 0..2 */
  74
  75                 responsive_design_wodth: 600,    /* page reflows for devices < 600 pixels wide */
  76                 pazpar2_url: "/service-proxy/",            /* URL */
  77                 service_proxy_auth: "/service-proxy-auth", /* URL */
  78                 // TODO: language_*, perpage_options, sort_options
  79             };
  80         </script>
  81 ~~~
  82
  83 jQuery plugin
  84 ------------------
  85
  86 The jQuery plugin version can be used by a single line of JavaScript code:
  87
  88 ~~~
  89         <script>jQuery.pazpar2();</script>
  90 ~~~
  91
  92 put the code in your page at the position where the metasearch should occur.
  93
  94 Here is an example of all possible options
  95
  96 ~~~
  97         jQuery.pazpar2({
  98             "layout": "popup",               /* "table" [default], "div", "popup" */
  99             "id_button": "input#mkwsButton", /* submit button id in search field */
 100             "id_popup": "#mkwsPopup",        /* internal id of popup window */
 101             "width": 880,                    /* popup width, should be at least 800 */
 102             "height": 760                    /* popup height, should be at least 600 */
 103         });
 104 ~~~
 105
 106
 107 Supported Browsers
 108 ------------------
 109
 110 Any modern HTML5 browser will work fine. JavaScript must be enabled.
 111
 112 * IE8 or later
 113 * Firefox 17 or later
 114 * Google Chrome 27 or later
 115 * Safari 6 or later
 116 * Opera  12 or later
 117 * iOS 6.x (iPhone, iPad)
 118 * Android 4.x
 119
 120 Not supported: IE6, IE7
 121
 122
 123 New Features since jsdemo
 124 --------------------------
 125
 126 - Supports basic pazpar2 and service-proxy requests
 127 - Simplified HTML
 128 - The search page is fully configurable by a JSON object
 129
 130
 131 Checklist before doing a release
 132 ---------------------------------
 133 - open the site, e.g. http://mkws-dev.indexdata.com/index-mike.html
 134 - open the debug/error console in your browser (alt-cmd-J, shift-cmd-J)
 135 - check the language links ("de", "da", "en")
 136 - run a search with few, but not to few results, e.g.: freebsd
 137 - check "Targets" | "Records" links
 138 - check "Next" and "Prev" links
 139 - click on the first hit and display details, click on an "URL" to jump to
 140   the local catalog or full text
 141 - limit search to a "Source"
 142 - limit search to an "Author"
 143 - sort results by "Title" and "newest"
 144 - what else?
 145
 146
 147
 148 What next?
 149 ----------
 150
 151 Main areas of work:
 152
 153 * Make MKWS robust to missing widgets
 154 * Clean up the code
 155
 156 - - -
 157
 158 Copyright 2013 IndexData ApS. <http://www.indexdata.com>