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