experiments/spclient/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://somesite.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
  33 Configuring a client
  34 --------------------
  35
  36 The application's HTML must contains the following elements as well as
  37 whatever makes up the application itself:
  38
  39 Prerequisites:
  40     <link rel="stylesheet" href="mkwsStyle.css" />
  41     <script type="text/javascript" src="http://code.jquery.com/jquery-1.10.0.min.js"></script>
  42     <script type="text/javascript" src="/libjs-pz2/pz2api.1.js"></script>
  43     <script type="text/javascript" src="mkws.js"></script>
  44 (Yes, we're using JQuery. We use it only in the most trivial ways, and
  45 could probably get rid of it without too much pain. I'd like to have
  46 mkws.js automatically pull in pz2api.1.js, too, so you don't need to
  47 do so many things, but that's not quite trivial.)
  48
  49 Then the following special <div>s can be added (with no content), and
  50 will be filled in by MKWS:
  51     <div id="mkwsSwitch"></div> -- switch between record and target views
  52     <div id="mkwsSearch"></div> -- search box and button
  53     <div id="mkwsRecords"></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 will not work correctly if any of these is
  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
  62 What next?
  63 ----------
  64
  65 Main areas of work:
  66 * Fix cross-site issues properly
  67 * Make MKWS robust to missing widgets
  68 * Make CSS more tightly targeted at MKWS elements only
  69 * Embed in a real, existing, site
  70 * Clean up the code
  71