tools/htdocs/README.markdown

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