tools/htdocs/README.markdown

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