1 % Using the MasterKey Widget Set to embed metasearching functionality in any web-site
8 There are lots of practical problems in building resource discovery
9 solutions. One of the biggest, and most ubiquitous is incorporating
10 metasearching functionality into existing web-sites -- for example,
11 content-management systems, library catalogues or intranets. In
12 general, even when access to metasearching is provided by simple
13 web-services such as [Pazpar2](http://www.indexdata.com/pazpar2),
14 integration work is seen as a major part of most projects.
16 Index Data provides several different toolkits for communicating with
17 its metasearching middleware, trading off varying degrees of
18 flexibility against convenience:
20 * libpz2.js -- a low-level JavaScript library for interrogating the
21 Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer
22 to implement simple JavaScript functions to display facets, records,
25 * masterkey-ui-core -- a higher-level, complex JavaScript library that
26 uses libpz2.js to provide the pieces needed for building a
27 full-featured JavaScript application.
29 * MasterKey Demo UI -- an example of a searching application built on
30 top of masterkey-ui-core. Available as a public demo at
31 http://mk2.indexdata.com/
33 * MKDru -- a toolkit for embedding MasterKey-like searching into
36 All of these approaches require programming to a greater or lesser
37 extent. Against this backdrop, we introduced MKWS (the MasterKey
38 Widget Set) -- a set of simple, very high-level HTML+CSS+JavaScript
39 components that can be incorporated into any web-site to provide
40 MasterKey searching facilities. By placing `<div>`s with well-known
41 identifiers in any HTML page, the various components of an application
42 can be embedded: search-boxes, results areas, target information, etc.
48 The following is a complete MKWS-based searching application:
52 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
53 <title>MKWS demo client</title>
54 <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
55 <link rel="stylesheet" href="http://mkws.indexdata.com/mkwsStyle.css" />
58 <div id="mkwsSearch"></div>
59 <div id="mkwsResults"></div>
63 Go ahead, try it! You don't even need a web-server. Just copy and
64 paste this HTML into a file on your computer -- `/tmp/magic.html`,
65 say -- and point your web-browser at it:
66 `file:///tmp/magic.html`. Just like that, you have working
73 If you know any HTML, the structure of the file will be familar to
74 you: the `<html>` element at the top level contains a `<head>` and a
75 `<body>`. In addition to whatever else you might want to put on your
76 page, you can add MKWS elements.
78 These fall into two categories. First, the prerequisites in the HTML
79 header, which are loaded from the tool site mkws.indexdata.com:
82 contains all the JavaScript needed by the widget-set.
85 provides the default CSS styling
87 Second, the `<div>` elements with special IDs that begin `mkws` can be
88 provided. These are filled in by the MKWS code, and provide the
89 components of the searching UI. The very simple application above has
90 only two such components: a search box and a results area. But more
91 are supported. The main `<div>`s are:
93 * `mkwsSearch` -- provides the search box and button.
95 * `mkwsResults` -- provides the results area, including a list of
96 brief records (which open out into full versions when clicked),
97 paging for large results sets, facets for refining a search,
98 sorting facilities, etc.
100 * `mkwsLang` -- provides links to switch between one of several
101 different UI languages. By default, English, Danish and German are
104 * `mkwsSwitch` -- provides links to switch between a view of the
105 result records and of the targets that provide them. Only
106 meaningful when `mkwsTargets` is also provided.
108 * `mkwsTargets` -- the area where per-target information will appear
109 when selected by the link in the `mkwsSwitch` area. Of interest
110 mostly for fault diagnosis rather than for end-users.
112 * `mkwsStat` --provides a status line summarising the statistics of
115 To see all of these working together, just put them all into the HTML
118 <div id="mkwsSwitch"></div>
119 <div id="mkwsLang"></div>
120 <div id="mkwsSearch"></div>
121 <div id="mkwsResults"></div>
122 <div id="mkwsTargets"></div>
123 <div id="mkwsStat"></div>
133 Control over HTML and CSS
134 -------------------------
138 More sophisticated applications will not simply place the `<div>`s
139 together, but position them carefully within an existing page
140 framework -- such as a Drupal template, an OPAC or a SharePoint page.
142 Breaking up mkwsResults
147 Popup results with jQuery UI
148 ----------------------------
153 Authentication and target configuration
154 ---------------------------------------
162 ### Configuration object
166 ### jQuery plugin invocation
170 ### The structure of the HTML generated by the MKWS widgets
176 Copyright (C) 2013 by IndexData ApS, <http://www.indexdata.com>