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.

As much of the searching functionality as possible is hosted on http://mkws.indexdata.com/ so that very simple applications such as https://example.indexdata.com/simple.html can have MasterKey searching with minimal effort. All you need to do is pull in our JavaScript and optional stylesheet, then add <div>s to your page that have special class attributes. We do the rest.

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

A minimal example

Here is a completely functional (though ugly) MKWS-based searching application [link]

<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
<div class="mkwsSearch"></div>
<div class="mkwsResults"></div>

That's it. A complete metasearching application. Everything else is refinement.

Configuring a client (short version)

The application's HTML must contain the following elements, as well as whatever makes up the application itself:

<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
<link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />

These lines pull in JavaScript code and the default styles. (The latter may be omitted or replaced with application-specific styles for the widgets.)

Then the following special <div>s can be added (with no content), and will be filled in by MKWS:

• <div class="mkwsSearch"></div> -- search box and button
• <div class="mkwsResults"></div> -- result list, including pager/sorting
• <div class="mkwsStat"></div> -- summary statistics
• <div class="mkwsSwitch"></div> -- switch between record and target views
• <div class="mkwsTargets"></div> -- target list, including status
• <div class="mkwsLang"></div> -- switch between languages, e.g. English, Danish and German

You can configure and control the client by creating an mkws_config object. Here is an example showing how to use options to offer a choice between English and German UI languages, and to default to sorting by title ascending:

<script type="text/javascript">
  var mkws_config = {
    lang_options: [ "en", "de" ],
    sort_default: "title:1"
  };
</script>

Detailed documentation

Apart from this file and its PDF version:

• The MKWS manual, including a reference section [PDF version]
• The MKWS developers' guide [PDF version]

Source code

The source code for MKWS is available on GitHub.

It is furnished under the GNU Lesser General Public License v3.0.

Widget files

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-v2.0.0.js -- A local copy of the Handlebars templating library, since it doesn't like to be hotlinked.
• Local copy of jquery-1.10.0.min.js
• Local copy of jquery.json-2.4.js
• Local copy of jsnlog.min.js
• 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

Specific 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) together with the CSS file (mkws.css) 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. and releases/mkws-0.9.1.css.

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 http://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.
• An application that draws together information from several widgets to present a topic page.

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.
  
• Another existing web-site, The Zthes specifications, which has been fitted with a popup MKWS search-box.

Real-world examples

• The One Repo, a growing repository that aggregates open-access papers from repositories around the world. (Read more in this blog-post: The world needs One Repo.)

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 .