tools/htdocs/README

   1 An embryonic MasterKey Widget Set
   2 =================================
   3
   4 This directory contains an embryonic MasterKey Widget Set, based
   5 initially on "jsdemo" though now far removed from those beginnnings.
   6
   7
   8 How this works
   9 --------------
  10
  11 The goal is to make it that as much of the searching functionality as
  12 possible is hosted on
  13         http://mkws.indexdata.com/
  14 so that very simple websites such as
  15         http://example.indexdata.com/
  16 can have MasterKey searching with minimal effort.
  17
  18 The following files must be hosted on mkws.indexdata.com:
  19         mkws.js
  20         mkwsStyle.css
  21         /libjs-pz2/pz2api.1.js (*)
  22
  23 The following files make up the application:
  24         index.html
  25         favicon.ico [optional]
  26         robots.txt [optional]
  27
  28 (At present, the client application's configuruation also needs an
  29 Alias for /service-proxy/, to avoid cross-site scripting issues. We
  30 will fix this.)
  31
  32 (*) if you don't have already installed libjs-pz2 on the machine, you can
  33 do it by installing a debian package or check it out from GIT:
  34 $ git clone ssh://git.indexdata.com:222/home/git/pub/libjs-pz2
  35
  36 Configuring a client
  37 --------------------
  38
  39 The application's HTML must contains the following elements as well as
  40 whatever makes up the application itself:
  41
  42 Prerequisites:
  43     <link rel="stylesheet" href="mkwsStyle.css" />
  44     <script type="text/javascript">
  45         var mkws_config = { };
  46     </script>
  47     <script type="text/javascript" src="http://code.jquery.com/jquery-1.10.0.min.js"></script>
  48     <script type="text/javascript" src="/libjs-pz2/pz2api.1.js"></script>
  49     <script type="text/javascript" src="mkws.js"></script>
  50 (Yes, we're using JQuery. We use it only in the most trivial ways, and
  51 could probably get rid of it without too much pain. I'd like to have
  52 mkws.js automatically pull in pz2api.1.js, too, so you don't need to
  53 do so many things, but that's not quite trivial.)
  54
  55 Then the following special <div>s can be added (with no content), and
  56 will be filled in by MKWS:
  57     <div id="mkwsSwitch"></div> -- switch between record and target views
  58     <div id="mkwsLang"></div>   -- switch between English, Danish and German
  59     <div id="mkwsSearch"></div> -- search box and button
  60     <div id="mkwsResults"></div> -- result list, including pager/sorting
  61     <div id="mkwsTargets"></div> -- target list, including status
  62     <div id="mkwsStat"></div> -- summary statistics
  63
  64 At present, MKWS will not work correctly if any of these is
  65 missing. One of the TODOs is to fix it so that it doesn't try to use
  66 whatever is not there, and just uses what is.
  67
  68
  69 You can configure and control the client with the JavaScript mkws_config object.
  70
  71 Here is an example of all possible options
  72     <script type="text/javascript">
  73         var mkws_config = {
  74                 use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
  75                 switch_menu: true,          /* true, false: show/hide Records|Targets menu */
  76                 lang_menu: true,            /* true, false: show/hide language menu */
  77                 sort_menu: true,            /* true, false: show/hide sort menu */
  78                 perpage_menu: true,         /* true, false: show/hide perpage menu */
  79                 lang_display: ["en", "de", "da"], /* display languages links for given
  80                                                      languages, [] for all */
  81                 facets: ["sources", "subjects", "authors"], /* display facets, in this order, [] for none */
  82                 sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
  83                 query_width: 50,            /* 5..50 */
  84                 perpage_default: 20,        /* 10, 20, 30, 50 */
  85                 lang: "en",                 /* "en", "de", "da" */
  86                 debug: 0,                   /* debug level for development: 0..2 */
  87
  88                 responsive_design: false    /* true, false: resize for smaller mobile devices */
  89                 pazpar2_url: "/pazpar2/search.pz2",        /* URL */
  90                 service_proxy_url: "/service-proxy/",      /* URL */
  91                 service_proxy_auth: "/service-proxy-auth", /* URL */
  92          };
  93     </script>
  94
  95 Note: the mkws_config object which must be loaded before the mkws.js and pz2api.js files.
  96
  97 Supported Browsers
  98 ------------------
  99
 100 Any modern HTML5 browser will work fine. JavaScript must be enabled.
 101
 102 * IE8 or later
 103 * Firefox 17 or later
 104 * Google Chrome 27 or later
 105 * Safari 6 or later
 106 * Opera  12 or later
 107 * iOS 6.x (iPhone, iPad)
 108 * Android 4.x
 109
 110 Not supported: IE6, IE7
 111
 112 New Features since jsdemo
 113 --------------------------
 114 - multilinguality: English (default), Danish, German
 115 - depends on the new pazpar2 JS library libjs-pz2/pz2api.1.js
 116   which will make the development of pazpar2 plugins faster and
 117   easier to share code between projects
 118 - supports basic pazpar2 and service-proxy requests
 119 - simplified HTML
 120 - the search page is fully configurable by a JSON object
 121
 122
 123 What next?
 124 ----------
 125
 126 Main areas of work:
 127 * Make MKWS robust to missing widgets
 128 * Clean up the code