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     <link rel="stylesheet" href="mkwsStyle.css" />
  42     <script type="text/javascript">
  43         var mkws_config = { };
  44     </script>
  45     <script type="text/javascript" src="http://code.jquery.com/jquery-1.10.0.min.js"></script>
  46     <script type="text/javascript" src="/libjs-pz2/pz2api.1.js"></script>
  47     <script type="text/javascript" src="mkws.js"></script>
  48 (Yes, we're using JQuery. We use it only in the most trivial ways, and
  49 could probably get rid of it without too much pain. I'd like to have
  50 mkws.js automatically pull in pz2api.1.js, too, so you don't need to
  51 do so many things, but that's not quite trivial.)
  52
  53 Then the following special <div>s can be added (with no content), and
  54 will be filled in by MKWS:
  55     <div id="mkwsSwitch"></div> -- switch between record and target views
  56     <div id="mkwsLang"></div>   -- switch between English, Danish and German
  57     <div id="mkwsSearch"></div> -- search box and button
  58     <div id="mkwsResults"></div> -- result list, including pager/sorting
  59     <div id="mkwsTargets"></div> -- target list, including status
  60     <div id="mkwsStat"></div> -- summary statistics
  61
  62 At present, MKWS will not work correctly if any of these is
  63 missing. One of the TODOs is to fix it so that it doesn't try to use
  64 whatever is not there, and just uses what is.
  65
  66
  67 You can configure and control the client with the JavaScript mkws_config object.
  68
  69 Here is an example of all possible options
  70     <script type="text/javascript">
  71         var mkws_config = {
  72                 use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
  73                 switch_menu: true,          /* true, false: show/hide Records|Targets menu */
  74                 lang_menu: true,            /* true, false: show/hide language menu */
  75                 sort_menu: true,            /* true, false: show/hide sort menu */
  76                 perpage_menu: true,         /* true, false: show/hide perpage menu */
  77                 lang_display: ["en", "de", "da"], /* display languages links for given
  78                                                      languages, [] for all */
  79                 facets: ["sources", "subjects", "authors"], /* display facets, in this order, [] for none */
  80                 sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
  81                 query_width: 50,            /* 5..50 */
  82                 perpage_default: 20,        /* 10, 20, 30, 50 */
  83                 lang: "en",                 /* "en", "de", "da" */
  84                 debug: 0,                   /* debug level for development: 0..2 */
  85
  86                 responsive_design: false    /* true, false: resize for smaller mobile devices */
  87                 pazpar2_url: "/pazpar2/search.pz2",        /* URL */
  88                 service_proxy_url: "/service-proxy/",      /* URL */
  89                 service_proxy_auth: "/service-proxy-auth", /* URL */
  90          };
  91     </script>
  92
  93 Note: the mkws_config object which must be loaded before the mkws.js and pz2api.js files.
  94
  95
  96 jQuery plugin
  97 ------------------
  98
  99 The jQuery plugin version, consisting of a single line of JavaScript code
 100
 101   <script>jQuery.pazpar2();</script>
 102
 103 put the code in your page at the position where the metasearch should occours.
 104
 105 Here is an example of all possible options
 106
 107   jQuery.pazpar2({"layout": "popup",    /* "table", "div", "popup", default is table */
 108                   "id_button": "input#mkwsButton", /* submit button id in search field */
 109                   "id_popup": "#mkwsPopup",        /* interal id of popup window */
 110                   "width": 880,         /* popup width, should be at least  800 */
 111                   "height": 760         /* popup height, should be at least 600 */
 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 New Features since jsdemo
 131 --------------------------
 132 - multilinguality: English (default), Danish, German
 133 - depends on the new pazpar2 JS library libjs-pz2/pz2api.1.js
 134   which will make the development of pazpar2 plugins faster and
 135   easier to share code between projects
 136 - supports basic pazpar2 and service-proxy requests
 137 - simplified HTML
 138 - the search page is fully configurable by a JSON object
 139
 140
 141 What next?
 142 ----------
 143
 144 Main areas of work:
 145 * Make MKWS robust to missing widgets
 146 * Clean up the code