1 % MKWS: the MasterKey Widget Set
6 Add metasearching to your web-site painlessly
7 ---------------------------------------------
9 The MasterKey Widget Set provides the easiest possible way to enhance
10 an existing web-site with customised searching across multiple
11 sources, ranking and merging the results.
13 As much of the searching functionality as possible is hosted on
14 <http://mkws.indexdata.com/> so that very simple applications such as
15 <http://example.indexdata.com/simple.html> can have MasterKey
16 searching with minimal effort. All you need to do is pull in our
17 JavaScript and optional stylesheet, then add `<div>`s to your page
18 that have special `class` attributes. We do the rest.
23 Any modern browser will work fine. JavaScript must be enabled.
27 * Google Chrome 27 or later
30 * iOS 6.x (iPhone, iPad)
33 Not supported: IE6, IE7
38 Here is a completely functional (though ugly) MKWS-based
39 searching application:
41 <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
42 <div class="mkwsSearch"></div>
43 <div class="mkwsResults"></div>
45 That's it. A complete metasearching application. Everything
48 Configuring a client (short version)
49 ------------------------------------
51 The application's HTML must contains the following elements as well as
52 whatever makes up the application itself:
57 <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
58 <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
61 Then the following special `<div>`s can be added (with no content), and
62 will be filled in by MKWS:
64 * `<div id="mkwsSwitch"></div>` -- switch between record and target views
65 * `<div id="mkwsLang"></div> ` -- switch between English, Danish and German
66 * `<div id="mkwsSearch"></div>` -- search box and button
67 * `<div id="mkwsResults"></div>` -- result list, including pager/sorting
68 * `<div id="mkwsTargets"></div>` -- target list, including status
69 * `<div id="mkwsStat"></div>` -- summary statistics
71 You can configure and control the client by creating an `mkws_config`
72 object before loading the widget-set. Here is an example showing how
73 to use options to offer a choice between English and German UI
74 languages, and to default to sorting by title ascending:
77 <script type="text/javascript">
79 lang_options: ["en", "de" ],
80 sort_default: "title:1"
85 For much more detail, see:
86 [Embedded metasearching with the MasterKey Widget Set](mkws-manual.html)
92 [<a href="index.pdf">PDF version</a>]
93 * The <a href="mkws-manual.html">MKWS manual, including a reference section.</a>
94 [<a href="mkws-manual.pdf">PDF version</a>]
95 * The <a href="mkws-developer.html">MKWS developers' guide.</a>
96 [<a href="mkws-developer.pdf">PDF version</a>]
101 Here are the files that this web-site provides:
103 * <a href="mkws.js">mkws.js</a> --
104 JavaScript code that powers the MasterKey Widget Set
105 * <a href="pazpar2/js/pz2.js">pazpar2/js/pz2.js</a> --
106 Low-level JavaScript library for access to the MasterKey web
108 * <a href="handlebars-v2.0.0.js">handlebars-v2.0.0.js</a> --
110 <a href="http://handlebarsjs.com/">the Handlebars templating library</a>,
111 since it doesn't like to be hotlinked.
112 * Local copy of <a href="jquery-1.10.0.min.js">jquery-1.10.0.min.js</a>
113 * Local copy of <a href="jquery.json-2.4.js">jquery.json-2.4.js</a>
114 * <a href="mkws-complete.js">mkws-complete.js</a> --
115 A single large JavaScript file containing everything needed for
116 MKWS to work: the widget-set itself, the API library, and
117 the prerequisites jQuery and Handlebars.
118 * <a href="mkws.css">mkws.css</a> --
119 A stylesheet which styles only MasterKey widgets, and does not
120 otherwise interfere with application-site's styles.
122 Minified versions of the MKWS JavaScript files are also available:
124 * <a href="mkws.min.js">mkws.min.js</a>
125 * <a href="mkws-complete.min.js">mkws-complete.min.js</a>
127 ### Specific versions
129 The links above to the various forms of the widget-set JavaScript
130 (<a href="mkws.js">mkws.js</a>,
131 <a href="mkws-complete.js">mkws-complete.js</a>,
132 <a href="mkws.min.js">mkws.min.js</a>
134 <a href="mkws-complete.min.js">mkws-complete.min.js</a>)
135 are always to the current versions of those
136 files. Applications that rely on a particular version can
137 instead use the specific numbered versions in
138 <a href="releases/">the releases area</a>,
140 <a href="releases/mkws-0.9.1.js">releases/mkws-0.9.1.js</a>.
142 The current version number is always in
143 <a href="VERSION">the VERSION file</a>.
145 Version history is in
146 <a href="NEWS">the NEWS file</a>.
148 Examples using the widget-set
149 -----------------------------
151 It's worth viewing the source of these to see how small they
152 are and how various things are done.
156 * A very simple application at
157 <a href="//example.indexdata.com/simple.html"
158 >//example.indexdata.com/simple.html</a>.
159 * <a href="//example.indexdata.com/minimal.html"
160 >The absolutely minimal application</a>
162 * <a href="//example.indexdata.com/language.html"
163 >A more detailed version</a>
164 that contains a configuration structure instead of accepting the
165 defaults. Includes a custom translation option to present the
166 application in Arabic.
167 * <a href="//example.indexdata.com/mobile.html"
168 >A version suitable for mobile devices</a>,
169 with a responsive design that moves components around depending on
172 ### Advanced examples
174 * An application that
175 <a href="//example.indexdata.com/lowlevel.html"
176 >uses lower-level MKWS components</a>
177 rather than the all-in-one `#mkwsResults` division,
178 allowing it to use a rather different layout.
179 * An application that specifies how to display brief and full records
180 <a href="//example.indexdata.com/templates.html"
181 >using Handlebar templates</a>.
183 <a href="http://handlebarsjs.com/"
184 >the templating language</a>.)
185 * An application that
186 <a href="http://example.indexdata.com/images.html?q=portrait"
187 >displays thumbnail images</a>.
188 * <a href="//example.indexdata.com/localauth.html"
189 >An application that uses a local authentication regime</a>,
190 and the corresponding
191 <a href="//example.indexdata.com/apache-config.txt"
192 >Apache2 configuration stanza</a>.
193 * <a href="//example.indexdata.com/popup.html"
194 >A version that uses a jQuery popup</a>.
196 ### Non-standard interfaces
198 * <a href="//example.indexdata.com/dict.html"
199 >An application that uses MKWS to find dictionary
200 definitions of words when you highlight them</a>.
201 * <a href="//example.indexdata.com/auto.html"
202 >An application that runs an automatic search on load</a>.
203 * An existing web-site,
204 <a href="http://sagp.miketaylor.org.uk/"
205 >The Self-Appointed Grammar Police</a>,
206 which has been fitted with an MKWS searching widget.
207 (See also the MKWS-widget customisations in
208 <a href="http://sagp.miketaylor.org.uk/style.css"
209 >that site's stylesheet</a>.)
211 * Another existing web-site,
212 <a href="http://zthes.z3950.org/"
213 >The Zthes specifications</a>,
214 which has been fitted with a popup MKWS search-box.
220 MKWS comes pre-configured to search in a set of a dozen or so
221 open-access targets, as a proof of concept. But you'll want
222 to use it to search your own selection of targets -- some open
223 access, some subscription.
225 We can set that up for you: email us on
226 <a href="mailto:info@indexdata.com"
227 >info@indexdata.com</a>.
231 Copyright (©) 2013-2014 Index Data ApS.
232 <a href="http://indexdata.com">`http://indexdata.com`</a>