-% An embryonic MasterKey Widget Set
+% The MasterKey Widget Set
% Mike Taylor; Wolfram Schneider
% 10 July 2013
Introduction
------------
-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
---------------
+This is the MasterKey Widget Set. The initial version was based on the
+"jsdemo" application distributed with pazpar2, but it is now far
+removed from those beginnnings.
As much of the searching functionality as possible is hosted on
<http://mkws.indexdata.com/>
The following files are hosted on `mkws.indexdata.com`:
-* `mkws.css`
* `mkws.js`
* `/pazpar2/js/pz2.js`
* `mkws-complete.js` -- a single file consisting of `mkws.js`,
jQuery (which it uses), Handlebars (ditto) and `pz2.js`
+* `mkws.css`
-Configuring a client
---------------------
+Supported Browsers
+------------------
+
+Any modern 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
+
+
+Configuring a client (short version)
+------------------------------------
The application's HTML must contains the following elements as well as
whatever makes up the application itself:
* `<div id="mkwsTargets"></div>` -- target list, including status
* `<div id="mkwsStat"></div>` -- summary statistics
-At present, MKWS may not work correctly if some of these are
-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 by creating an `mkws_config`
object _before_ loading the widget-set. 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 */
- show_lang: true, /* true, false: show/hide language menu */
- show_sort: true, /* true, false: show/hide sort menu */
- show_perpage: true, /* true, false: show/hide perpage menu */
- lang_options: ["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_level: 0, /* debug level for development: 0..2 */
-
- responsive_design_wodth: 600, /* page reflows for devices < 600 pixels wide */
- pazpar2_url: "/service-proxy/", /* URL */
- service_proxy_auth: "/service-proxy-auth", /* URL */
- // TODO: language_*, perpage_options, sort_options
- };
- </script>
-~~~
-
-jQuery plugin
-------------------
-
-The jQuery plugin version can be used by a single line of JavaScript code:
-
-~~~
- <script>jQuery.pazpar2();</script>
-~~~
-
-put the code in your page at the position where the metasearch should occur.
-
-Here is an example of all possible options
-
-~~~
- jQuery.pazpar2({
- "layout": "popup", /* "table" [default], "div", "popup" */
- "id_button": "input#mkwsButton", /* submit button id in search field */
- "id_popup": "#mkwsPopup", /* internal id of popup window */
- "width": 880, /* popup width, should be at least 800 */
- "height": 760 /* popup height, should be at least 600 */
- });
+ <script type="text/javascript">
+ var mkws_config = {
+ use_service_proxy: true, /* true, flase: use service proxy instead pazpar2 */
+ show_lang: true, /* true, false: show/hide language menu */
+ show_sort: true, /* true, false: show/hide sort menu */
+ show_perpage: true, /* true, false: show/hide perpage menu */
+ lang_options: ["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_level: 0, /* debug level for development: 0..2 */
+
+ responsive_design_wodth: 600, /* page reflows for devices < 600 pixels wide */
+ pazpar2_url: "/service-proxy/", /* URL */
+ service_proxy_auth: "/service-proxy-auth", /* URL */
+ // TODO: language_*, perpage_options, sort_options
+ };
+ </script>
~~~
+For much more detail, see
+[the MKWS whitepaper](whitepaper.html).
-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
---------------------------
-
-- Supports basic pazpar2 and service-proxy requests
-- Simplified HTML
-- The search page is fully configurable by a JSON object
-
-
-Checklist before doing a release
----------------------------------
-- open the site, e.g. http://mkws-dev.indexdata.com/index-mike.html
-- open the debug/error console in your browser (alt-cmd-J, shift-cmd-J)
-- check the language links ("de", "da", "en")
-- run a search with few, but not to few results, e.g.: freebsd
-- check "Targets" | "Records" links
-- check "Next" and "Prev" links
-- click on the first hit and display details, click on an "URL" to jump to
- the local catalog or full text
-- limit search to a "Source"
-- limit search to an "Author"
-- sort results by "Title" and "newest"
-- what else?
-
-
-
-What next?
-----------
-
-Main areas of work:
-
-* Make MKWS robust to missing widgets
-* Clean up the code
- - -
-\(c) 2013 by IndexData ApS, <http://www.indexdata.com>
+Copyright 2013 IndexData ApS. <http://indexdata.com>
body {
font-family: Gill Sans, "Gillius ADF", Gillius, GilliusADF, Sans-Serif;
}
- h1 { color: #606060 }
- p { font-weight: bold }
+ h1 { font-weight: normal; color: #606060 }
+ h2 { font-size: 100% }
+ .pane { padding: 0em 1em; margin: 0.75em;
+ border: 0.5em solid #eee;
+ border-radius: 1em;
+ background-image: url('images/mkws-logo-48x48-light.png');
+ background-repeat: no-repeat;
+ background-position: right top;
+ background-color: #eee;
+ }
+ .nologo { background-image: none }
+ pre { background: #ddd; padding: 0.5em; }
</style>
</head>
<body>
+ <img src="images/mkws-logo-300px.png" alt="MKWS logo" =
+ style="float:right; margin: 1.5em"/>
<h1>MKWS: the MasterKey Widget Set</h1>
- <p>
- This site contains tools, not content:
- </p>
- <ul>
- <li>
- <a href="mkws.js">mkws.js</a>
- --
- JavaScript code that powers the MasterKey Widget Set
- </li>
- <li>
- <a href="/pazpar2/js/pz2.js">/pazpar2/js/pz2.js</a>
- --
- Low-level JavaScript library for access to the MasterKey web
- service.
- </li>
- <li>
- <a href="mkws-complete.js"
- >mkws-complete.js</a>
- --
- A single large JavaScript file containing everything needed for
- MKWS to work: the widget-set itself, the API library, and any
- additional prerequisites such as jQuery.
- </li>
- <li>
- <a href="mkws.css">mkws.css</a>
- --
- A stylesheet which styles only MasterKey widgets, and does not
- otherwise interfere with application-site's styles.
- <!--
- <p style="color:darkred">
- Note. This is not yet quite true: the stylesheet needs tweaking
- to make it more specific to only the MKWS components. At present
- it spills over into styling parts of the containing site, too.
- </p>
- -->
- </li>
- </ul>
- <p>
- For examples of how to use the widget-set, see:
- </p>
- <ul>
- <li>
- A very simple application at
- <a href="http://example.indexdata.com/"
- >http://example.indexdata.com/</a>.
- It's worth viewing the source to see how small it is.
- </li>
- <li>
- <a href="http://example.indexdata.com/language.html"
- >A more detailed version</a>
- that contains a configuration structure instead of accepting
- the defaults. Includes a custom translation option to present
- the application in Arabic.
- </li>
- <li>
- The
- <a href="http://example.indexdata.com/jquery.html"
- >jQuery plugin</a>
- version, consisting of a single line of JavaScript code.
- </li>
- <li>
- An application that
- <a href="http://example.indexdata.com/lowlevel.html"
- >uses lower-level MKWS components</a>
- rather than the all-in-one <tt>#mkwsResults</tt> division,
- allowing it to use a rather different layout.
- </li>
- <li>
- An application that specifies how to display brief and full records
- <a href="http://example.indexdata.com/templates.html"
- >using Handlebar templates</a>.
- (Read about
- <a href="http://handlebarsjs.com/"
- >the templating language</a>.)
- </li>
- <li>
- <a href="http://example.indexdata.com/mobile.html"
- >A version suitable for mobile devices</a>,
- with a responsive design that moves components around
- depending on the screen size.
- </li>
- <li>
- <a href="http://example.indexdata.com/popup.html"
- >A version that uses a jQuery popup</a>.
- </li>
- <li>
- <a href="http://example.indexdata.com/dict.html"
- >An application that uses MKWS to find dictionary
- definitions of words when you highlight them</a>.
- </li>
- <li>
- <a href="http://example.indexdata.com/auto.html"
- >An application that runs an automatic search on load</a>.
- </li>
- <li>
- <a href="http://example.indexdata.com/localauth.html"
- >An application that uses a local authentication regime</a>,
- and the corresponding
- <a href="http://example.indexdata.com/apache-config.txt"
- >Apache2 configuration stanza</a>.
- </li>
- <li>
- An existing web-site,
- <a href="http://sagp.miketaylor.org.uk/"
- >The Self-Appointed Grammar Police</a>,
- which has been fitted with an MKWS searching widget.
- (See also the MKWS-widget customisations in
- <a href="http://sagp.miketaylor.org.uk/style.css"
- >that site's stylesheet</a>.)
- </li>
- <li>
- Another existing web-site,
- <a href="http://zthes.z3950.org/"
- >The Zthes specifications</a>,
- which has been fitted with a popup MKWS search-box.
- </li>
- </ul>
- <p>
- The set of targets can be maintained:
- </p>
- <ul>
- <li>
- Use the main
+
+ <div class="pane nologo">
+ <h2>Add metasearching to your web-site painlessly</h2>
+ <p>
+ The MasterKey Widget Set provides the easiest possible way to
+ enhance an existing web-site with customised searching across
+ multiple sources, ranking and merging the results.
+ </p>
+ <p>
+ All you need to do is pull in our JavaScript and optional
+ stylesheet, then add <tt><div></tt>s to your page that
+ have special <tt>id</tt> attributes. We do the rest.
+ </p>
+ </div>
+
+ <div class="pane">
+ <h2>Example</h2>
+ <p>
+ Here is a completely functional (though ugly) MKWS-based
+ searching application:
+ </p>
+ <blockquote>
+ <pre>
+<script type="text/javascript"
+ src="http://mkws.indexdata.com/mkws-complete.js"></script>
+<div id="mkwsSearch"></div>
+<div id="mkwsResults"></div></pre>
+ </blockquote>
+ <p>
+ That's it. A complete metasearching application. Everything
+ else is refinement.
+ </p>
+ </div>
+
+ <div class="pane">
+ <h2>Documentation</h2>
+ <ul>
+ <li>
+ The <a href="README.html">README</a> -- mostly technical details.
+ </li>
+ <li>
+ The <a href="whitepaper.html">whitepaper, including a
+ reference section.</a>
+ This is a much better introduction.
+ </li>
+ </ul>
+ </div>
+
+ <div class="pane">
+ <h2>Tools</h2>
+ <p>
+ Here are the files that this web-site provides:
+ </p>
+ <ul>
+ <li>
+ <a href="mkws.js">mkws.js</a>
+ --
+ JavaScript code that powers the MasterKey Widget Set
+ </li>
+ <li>
+ <a href="pazpar2/js/pz2.js">pazpar2/js/pz2.js</a>
+ --
+ Low-level JavaScript library for access to the MasterKey web
+ service.
+ </li>
+ <li>
+ <a href="handlebars-v1.1.2.js">handlebars-v1.1.2.js</a>
+ --
+ A local copy of
+ <a href="http://handlebarsjs.com/"
+ >the Handlebars templating library</a>,
+ since it doesn't like to be hotlinked.
+ </li>
+ <li>
+ <a href="mkws-complete.js"
+ >mkws-complete.js</a>
+ --
+ A single large JavaScript file containing everything needed for
+ MKWS to work: the widget-set itself, the API library, and
+ the prerequisites jQuery and Handlebars.
+ </li>
+ <li>
+ <a href="mkws.css">mkws.css</a>
+ --
+ A stylesheet which styles only MasterKey widgets, and does not
+ otherwise interfere with application-site's styles.
+ </li>
+ </ul>
+ <p>
+ (This domain also hosts two web-service endpoints that are used by
+ running MKWS-based applications:
+ <tt>/service-proxy-auth</tt>
+ is used to authenticate new sessions and
+ <code>/service-proxy/</code>
+ is the main endpoint for searching and retrieval. But there is
+ no need to use these directly: the widgets take care of that.)
+ </li>
+ </ul>
+ </div>
+
+ <div class="pane">
+ <h2>Examples using the widget-set</h2>
+ <p>
+ It's worth viewing the source of these to see how small they
+ are and how various things are done.
+ </p>
+ <ul>
+ <li>
+ A very simple application at
+ <a href="http://example.indexdata.com/"
+ >http://example.indexdata.com/</a>.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/minimal.html"
+ >The absolutely minimal application</a>
+ listed above.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/language.html"
+ >A more detailed version</a>
+ that contains a configuration structure instead of accepting
+ the defaults. Includes a custom translation option to present
+ the application in Arabic.
+ </li>
+ <li>
+ The
+ <a href="http://example.indexdata.com/jquery.html"
+ >jQuery plugin</a>
+ version, consisting of a single JavaScript statement.
+ </li>
+ <li>
+ An application that
+ <a href="http://example.indexdata.com/lowlevel.html"
+ >uses lower-level MKWS components</a>
+ rather than the all-in-one <tt>#mkwsResults</tt> division,
+ allowing it to use a rather different layout.
+ </li>
+ <li>
+ An application that specifies how to display brief and full records
+ <a href="http://example.indexdata.com/templates.html"
+ >using Handlebar templates</a>.
+ (Read about
+ <a href="http://handlebarsjs.com/"
+ >the templating language</a>.)
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/mobile.html"
+ >A version suitable for mobile devices</a>,
+ with a responsive design that moves components around
+ depending on the screen size.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/popup.html"
+ >A version that uses a jQuery popup</a>.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/dict.html"
+ >An application that uses MKWS to find dictionary
+ definitions of words when you highlight them</a>.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/auto.html"
+ >An application that runs an automatic search on load</a>.
+ </li>
+ <li>
+ <a href="http://example.indexdata.com/localauth.html"
+ >An application that uses a local authentication regime</a>,
+ and the corresponding
+ <a href="http://example.indexdata.com/apache-config.txt"
+ >Apache2 configuration stanza</a>.
+ </li>
+ <li>
+ An existing web-site,
+ <a href="http://sagp.miketaylor.org.uk/"
+ >The Self-Appointed Grammar Police</a>,
+ which has been fitted with an MKWS searching widget.
+ (See also the MKWS-widget customisations in
+ <a href="http://sagp.miketaylor.org.uk/style.css"
+ >that site's stylesheet</a>.)
+ </li>
+ <li>
+ Another existing web-site,
+ <a href="http://zthes.z3950.org/"
+ >The Zthes specifications</a>,
+ which has been fitted with a popup MKWS search-box.
+ </li>
+ </ul>
+ </div>
+
+ <div class="pane">
+ <h2>Target maintainance</h2>
+ <p>
+ The set of targets provided by MKWS by default can be
+ maintained using
+ <a href="http://www.indexdata.com/mkadmin">MKAdmin</a>
+ by users with appropriate credentials.
+ Go to
<a href="http://mk2.indexdata.com/console/"
- >MasterKey Admin Console</a>,
+ >the main console</a>
and act as the "MK Demo" library administrator.
- </li>
- </ul>
- <p>
- Documentation:
+ </p>
+ </div>
+
+ <p style="text-align: right; font-size: small">
+ Copyright © 2013 IndexData ApS.
+ <a href="http://indexdata.com"><code>http://indexdata.com</code></a>
</p>
- <ul>
- <li>
- The <a href="whitepaper.html">The whitepaper, including a reference section.</a>
- </li>
- <li>
- The <a href="README.html">README.html</a>
- </li>
- <li>
- The <a href="html-structure.txt"
- >structure of the HTML generated by the MKWS widgets</a>,
- which can be used to guide the customisation of its CSS styles.
- </li>
- </ul>
</body>
</html>
projects / mkws-moved-to-github.git / commitdiff
