From 93790660d03d6a675bf0f8d9a862ea9afe2de1b8 Mon Sep 17 00:00:00 2001
From: Mike Taylor <mike@indexdata.com>
Date: Wed, 10 Jul 2013 17:46:33 +0100
Subject: [PATCH] New file, README.markdown. Will replace plain-text README,
 but translation is not yet complete.

---
 tools/htdocs/README.markdown |  146 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 tools/htdocs/README.markdown

diff --git a/tools/htdocs/README.markdown b/tools/htdocs/README.markdown
new file mode 100644
index 0000000..a05948b
--- /dev/null
+++ b/tools/htdocs/README.markdown
@@ -0,0 +1,146 @@
+% An embryonic MasterKey Widget Set
+% Mike Taylor; Wolfram Schneider
+% 10 July 2013
+
+
+This directory contains an embryonic MasterKey Widget Set. The initial
+version was based on the "jsdemo" application distributed with
+pazpar2, but it is now far removed from those beginnnings.
+
+
+How this works
+--------------
+
+The goal is to make it that as much of the searching functionality as
+possible is hosted on
+	<http://mkws.indexdata.com/>
+so that very simple websites such as
+	<http://example.indexdata.com/>
+can have MasterKey searching with minimal effort.
+
+The following files are hosted on mkws.indexdata.com:
+
+* `mkws.js`
+* `mkwsStyle.css`
+* `/libjs-pz2/pz2api.1.js`
+
+The following files make up an application:
+
+* `index.html`
+* `favicon.ico` [_optional_]
+* `robots.txt` [_optional_]
+
+
+Configuring a client
+--------------------
+
+The application's HTML must contains the following elements as well as
+whatever makes up the application itself:
+
+Prerequisites:
+    <link rel="stylesheet" href="mkwsStyle.css" />
+    <script type="text/javascript">
+	var mkws_config = { };
+    </script>
+    <script type="text/javascript" src="http://code.jquery.com/jquery-1.10.0.min.js"></script>
+    <script type="text/javascript" src="/libjs-pz2/pz2api.1.js"></script>
+    <script type="text/javascript" src="mkws.js"></script>
+(Yes, we're using JQuery. We use it only in the most trivial ways, and
+could probably get rid of it without too much pain. I'd like to have
+mkws.js automatically pull in pz2api.1.js, too, so you don't need to
+do so many things, but that's not quite trivial.)
+
+Then the following special <div>s can be added (with no content), and
+will be filled in by MKWS:
+    <div id="mkwsSwitch"></div> -- switch between record and target views
+    <div id="mkwsLang"></div>   -- switch between English, Danish and German
+    <div id="mkwsSearch"></div> -- search box and button
+    <div id="mkwsResults"></div> -- result list, including pager/sorting
+    <div id="mkwsTargets"></div> -- target list, including status
+    <div id="mkwsStat"></div> -- summary statistics
+
+At present, MKWS will not work correctly if any of these is
+missing. One of the TODOs is to fix it so that it doesn't try to use
+whatever is not there, and just uses what is.
+
+
+You can configure and control the client with the JavaScript mkws_config object.
+
+Here is an example of all possible options
+    <script type="text/javascript">
+        var mkws_config = {
+                use_service_proxy: true,    /* true, flase: use service proxy instead pazpar2 */
+		switch_menu: true, 	    /* true, false: show/hide Records|Targets menu */
+		lang_menu: true, 	    /* true, false: show/hide language menu */
+		sort_menu: true, 	    /* true, false: show/hide sort menu */
+		perpage_menu: true, 	    /* true, false: show/hide perpage menu */
+	        lang_display: ["en", "de", "da"], /* display languages links for given
+				                     languages, [] for all */
+		facets: ["sources", "subjects", "authors"], /* display facets, in this order, [] for none */
+                sort_default: "relevance",  /* "relevance", "title:1", "date:0", "date:1" */
+		query_width: 50,	    /* 5..50 */
+                perpage_default: 20,	    /* 10, 20, 30, 50 */
+                lang: "en",                 /* "en", "de", "da" */
+		debug: 0,     		    /* debug level for development: 0..2 */
+
+		responsive_design: false    /* true, false: resize for smaller mobile devices */
+		pazpar2_url: "/pazpar2/search.pz2",   	   /* URL */
+		service_proxy_url: "/service-proxy/", 	   /* URL */
+		service_proxy_auth: "/service-proxy-auth", /* URL */
+         };
+    </script>
+
+Note: the mkws_config object which must be loaded before the mkws.js and pz2api.js files.
+
+
+jQuery plugin
+------------------
+
+The jQuery plugin version, consisting of a single line of JavaScript code
+
+  <script>jQuery.pazpar2();</script>
+
+put the code in your page at the position where the metasearch should occours.
+
+Here is an example of all possible options
+
+  jQuery.pazpar2({"layout": "popup", 	/* "table", "div", "popup", default is table */
+		  "id_button": "input#mkwsButton", /* submit button id in search field */
+		  "id_popup": "#mkwsPopup",        /* interal id of popup window */
+		  "width": 880,		/* popup width, should be at least  800 */ 
+		  "height": 760 	/* popup height, should be at least 600 */
+  });
+
+
+Supported Browsers
+------------------
+
+Any modern HTML5 browser will work fine. JavaScript must be enabled.
+
+* IE8 or later
+* Firefox 17 or later
+* Google Chrome 27 or later
+* Safari 6 or later
+* Opera  12 or later
+* iOS 6.x (iPhone, iPad)
+* Android 4.x
+
+Not supported: IE6, IE7
+
+New Features since jsdemo
+--------------------------
+- multilinguality: English (default), Danish, German
+- depends on the new pazpar2 JS library libjs-pz2/pz2api.1.js
+  which will make the development of pazpar2 plugins faster and
+  easier to share code between projects
+- supports basic pazpar2 and service-proxy requests
+- simplified HTML
+- the search page is fully configurable by a JSON object
+
+
+What next?
+----------
+
+Main areas of work:
+* Make MKWS robust to missing widgets
+* Clean up the code
-- 
1.7.10.4