From: Mike Taylor Date: Mon, 13 Oct 2014 16:00:28 +0000 (+0100) Subject: New file, index.markdown, compiles to an index.html very similar to X-Git-Tag: 1.0.0~241 X-Git-Url: http://lists.indexdata.com/cgi-bin?a=commitdiff_plain;h=7307cbb1eb60bd08e24190251c9f4b5750782abc;p=mkws-moved-to-github.git New file, index.markdown, compiles to an index.html very similar to the old hand-written one. (Last bits of style harmonisation not quite complete, but the big stuff is done.) --- diff --git a/doc/index.markdown b/doc/index.markdown new file mode 100644 index 0000000..1587456 --- /dev/null +++ b/doc/index.markdown @@ -0,0 +1,179 @@ +% MKWS: the MasterKey Widget Set + + + +Add metasearching to your web-site painlessly +--------------------------------------------- + +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. + +All you need to do is pull in our JavaScript and optional stylesheet, +then add `
`s to your page that have special `id` attributes. We +do the rest. + +A minimal example +----------------- + +Here is a completely functional (though ugly) MKWS-based +searching application: + + +
+
+ +That's it. A complete metasearching application. Everything +else is refinement. + +Documentation +------------- + +* The README -- mostly technical details. +* The MKWS manual, including a reference section. + This is a much better introduction. + +Tools +----- + +Here are the files that this web-site provides: + +* mkws.js -- + JavaScript code that powers the MasterKey Widget Set +* pazpar2/js/pz2.js -- + Low-level JavaScript library for access to the MasterKey web + service. +* handlebars-v1.1.2.js -- + A local copy of + the Handlebars templating library, + since it doesn't like to be hotlinked. +* mkws-complete.js -- + 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. +* mkws.css -- + A stylesheet which styles only MasterKey widgets, and does not + otherwise interfere with application-site's styles. + +Minified versions of the MKWS JavaScript files are also available: + +* mkws.min.js +* mkws-complete.min.js + +(This domain also hosts two web-service endpoints that are used by +running MKWS-based applications: +`/service-proxy-auth` +is used to authenticate new sessions and +`/service-proxy/` +is the main endpoint for searching and retrieval. But there is +no need to use these directly: the widgets take care of that.) + +Versions +-------- + +The links above to the various forms of the widget-set JavaScript +(mkws.js, +mkws-complete.js, +mkws.min.js +and +mkws-complete.min.js) +are always to the current versions of those +files. Applications that rely on a particular version can +instead use the specific numbered versions in +the releases area, +for example +releases/mkws-0.9.1.js. + +The current version number is always in +the VERSION file. + +Version history is in +the NEWS file. + +Examples using the widget-set +----------------------------- + +It's worth viewing the source of these to see how small they +are and how various things are done. + +### Simple examples + +* A very simple application at + //example.indexdata.com/simple.html. +* The absolutely minimal application + listed above. +* A more detailed version + that contains a configuration structure instead of accepting the + defaults. Includes a custom translation option to present the + application in Arabic. +* A version suitable for mobile devices, + with a responsive design that moves components around depending on + the screen size. + +### Advanced examples + +* An application that + uses lower-level MKWS components + rather than the all-in-one `#mkwsResults` division, + allowing it to use a rather different layout. +* An application that specifies how to display brief and full records + using Handlebar templates. + (Read about + the templating language.) +* An application that + displays thumbnail images. +* An application that uses a local authentication regime, + and the corresponding + Apache2 configuration stanza. +* A version that uses a jQuery popup. + +### Non-standard interfaces + +* An application that uses MKWS to find dictionary + definitions of words when you highlight them. +* An application that runs an automatic search on load. +* An existing web-site, + The Self-Appointed Grammar Police, + which has been fitted with an MKWS searching widget. + (See also the MKWS-widget customisations in + that site's stylesheet.) + + +Target selection +---------------- + +MKWS comes pre-configured to search in a set of a dozen or so +open-access targets, as a proof of concept. But you'll want +to use it to search your own selection of targets -- some open +access, some subscription. + +We can set that up for you: email us on +info@indexdata.com. + +

+Copyright (©) 2013-2014 Index Data ApS. +`http://indexdata.com` +