-% Embedded metasearching with the MasterKey Widget Set
+% The MKWS manual: embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% 30 July 2014
+% October 2014
Introduction
its metasearching middleware, trading off varying degrees of
flexibility against convenience:
-* pz2.js -- a low-level JavaScript library for interrogating the
- Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer
- to create JavaScript applications display facets, records, etc. that
- are fetched from the metasearching middleware.
+* [pz2.js](http://www.indexdata.com/pazpar2/doc/ajaxdev.html) --
+ a low-level JavaScript library for interrogating the
+ [Service Proxy](http://www.indexdata.com/service-proxy/)
+ and
+ [Pazpar2](http://www.indexdata.com/pazpar2/).
+ It allows the HTML/JavaScript programmer
+ to create JavaScript applications to display facets, records,
+ etc. that are fetched from the metasearching middleware.
* masterkey-ui-core -- a higher-level, complex JavaScript library that
uses pz2.js to provide the pieces needed for building a
* MasterKey Demo UI -- an example of a searching application built on
top of masterkey-ui-core. Available as a public demo at
- http://mk2.indexdata.com/
+ <http://mk2.indexdata.com/>
-* MKDru -- a toolkit for embedding MasterKey-like searching into
- Drupal sites.
+* [MKDru](http://www.indexdata.com/masterkey-drupal) --
+ a toolkit for embedding MasterKey-like searching into
+ [Drupal](https://www.drupal.org/)
+ sites.
All of these approaches require programming to a greater or lesser
-extent. Against this backdrop, we introduced MKWS (the MasterKey
-Widget Set) -- a set of simple, very high-level HTML+CSS+JavaScript
+extent. Against this backdrop, we introduced
+[MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
+-- a set of simple, very high-level HTML+CSS+JavaScript
components that can be incorporated into any web-site to provide
MasterKey searching facilities. By placing `<div>`s with well-known
MKWS classes in any HTML page, the various components of an application
The templates used by the core widgets can be viewed in [our git
repository](http://git.indexdata.com/?p=mkws.git;a=tree;f=src/mkws.templates;).
-Replacement values are documented in a comment at the top of each template so
+Parameters are documented in a comment at the top of each template so
you can see what's going where. If all you want to do is add a CSS class to
something or change a `span` to a `div` it's easy to just copy the existing
template and make your edits.
as a `<script>` tag marked with a class of `mkwsTemplate_Foo` where Foo is the
name of the template you want to override (typically the name of the widget).
Inline Handlebars templates are distinguished from Javascript via a
-`type="text/x-handlebars-template` attribute. For example, to override the
+`type="text/x-handlebars-template"` attribute. For example, to override the
Pager template you would include this in your document:
<script class="mkwsTemplate_Pager" type="text/x-handlebars-template">
The Facet template has a special feature where you can override it on a
per-facet basis by adding a dash and the facet name as a suffix eg.
-`Facet-Subjects` rather than `Facet`.
+`Facet-Subjects` rather than `Facet`. (So `class="mkwsTemplate_Facet-Subjects"`)
You can also explicitly specify a different template for a particular instance
of a widget by providing the name of your alternative (eg. SpecialPager) as the
-value of the `template` key in the MKWS config object for that widget
-(usually via the `data-mkws-config` attribute).
+value of the `template` key in the MKWS config object for that widget:
+for example, `<div class="mkwsPager" template="specialPager"/>`.
Templates for MKWS can also be
[precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled
template of the same name is found in the `Handlebars.templates` object, it
will be used instead of the default.
-Templating metadata
--------------------
+Inspecting metadata for templating
+----------------------------------
MKWS makes requests to Service Proxy or Pazpar2 that perform the actual
searching. Depending on how these are configured and what is available from the
targets you are searching there may be more data available than what is
-presented by the default templates.
+presented by the default templates. In this case, you can redefine the
+`Record` template to include more fields in the full-record popup.
Handlebars offers a convenient log helper that will output the contents of a
variable for you to inspect. This lets you look at exactly what is being
projects / mkws-moved-to-github.git / blobdiff