X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=a0415b806d6c2be105d05e59f86a13a19aca7d03;hb=b5cee14f163b48d8da1bded7120dee1eb6323b72;hp=810ee4ed8062bdacc676576faa44b393cca5ab2d;hpb=044013582f14efad3e3e48f17fde0c8d0964630a;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 810ee4e..a0415b8 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -1,6 +1,6 @@
-% 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
@@ -19,10 +19,14 @@ Index Data provides several different toolkits for communicating with
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
@@ -30,14 +34,17 @@ flexibility against convenience:
* 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/
+
-* 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 `
`s with well-known
MKWS classes in any HTML page, the various components of an application
@@ -47,27 +54,26 @@ can be embedded: search-boxes, results areas, target information, etc.
Simple Example
==============
-The following is a complete MKWS-based searching application:
+The following is
+[a complete MKWS-based searching application](//example.indexdata.com/simple.html):
MKWS demo client
-
-
+
+
-
-
+
+
-Go ahead, try it! You don't even need a web-server. Just copy and
-paste this HTML into a file on your computer -- `/tmp/magic.html`,
-say -- and point your web-browser at it:
-`file:///tmp/magic.html`. Just like that, you have working
-metasearching.
-
+Go ahead, try it! Simply put the above in a file (e.g index.html),
+drop it into a folder accessible with an ordinary web-server (e.g
+Apache) and load it in your web browser. Just like that, you have
+working metasearching.
How the example works
---------------------
@@ -78,7 +84,7 @@ you: the `` element at the top level contains a `` and a
page, you can add MKWS elements.
These fall into two categories. First, the prerequisites in the HTML
-header, which are loaded from the tool site mkws.indexdata.com:
+header, which are loaded from the tool site `mkws.indexdata.com`:
* `mkws-complete.js`
contains all the JavaScript needed by the widget-set.
@@ -99,9 +105,8 @@ results area. But more are supported. The main `
`s are:
paging for large results sets, facets for refining a search,
sorting facilities, etc.
-* `mkwsLang` -- provides links to switch between one of several
- different UI languages. By default, English, Danish and German are
- provided.
+* `mkwsStat` --provides a status line summarising the statistics of
+ the various targets.
* `mkwsSwitch` -- provides links to switch between a view of the
result records and of the targets that provide them. Only
@@ -111,8 +116,9 @@ results area. But more are supported. The main `
`s are:
when selected by the link in the `mkwsSwitch` area. Of interest
mostly for fault diagnosis rather than for end-users.
-* `mkwsStat` --provides a status line summarising the statistics of
- the various targets.
+* `mkwsLang` -- provides links to switch between one of several
+ different UI languages. By default, English, Danish and German are
+ provided.
To see all of these working together, just put them all into the HTML
`` like so:
@@ -192,6 +198,107 @@ containers. The structures used by the widget-set are described in the
reference guide below.
+Customised display using Handlebars templates
+=============================================
+
+A lot can be done by styling widgets in CSS and changing basic MKWS config
+options. For further customisation, MKWS allows you to change the markup it
+outputs for any widget. This is done by overriding the
+[Handlebars](http://handlebarsjs.com/) template used to generate it. In general
+these consist of `{{things in double braces}}` that are replaced by values from
+the system. For details of Handlebars template syntax, see [the online
+documentation](http://handlebarsjs.com/).
+
+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;).
+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.
+
+Overriding templates
+--------------------
+
+To override the template for a widget, include it inline in the document
+as a `
+
+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`. (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:
+for example, ``.
+
+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.
+
+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. 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
+returned by the back end without needing to use a Javascript debugger. For
+example, you might prepend `{{log hits}}` to the Records template in order to
+see what is being returned with each search result in the list. In order for
+this to work you'll need to enable verbose output from Handlebars which is done
+by including this line or similar:
+
+
+
+Internationalisation
+--------------------
+
+If you would like your template to use the built in translation functionality,
+output locale specific text via the mkws-translate helper like so:
+`{{{mkws-translate "a few words"}}}`.
+
+Example
+-------
+
+Rather than use the included AJAX helpers to render record details inline,
+here's a Records template that will link directly to the source via the address
+provided in the metadata as the first element of `md-electronic-url`:
+
+
+
+For a more involved example where markup for multiple widgets is decorated with
+[Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is
+employed, take a look at the source of
+[topic.html](http://example.indexdata.com/topic.html?q=water).
+
+
Refinements
===========
@@ -207,41 +314,6 @@ day, a welcome message or a help page. This can be done by placing an
search is made.
-Customised display using Handlebars templates
----------------------------------------------
-
-Certain aspects of the widget-set's display can be customised by
-providing Handlebars templates with well-known classes that begin with
-the string `mkwsTemplate_`. At present, the supported templates are:
-
-* `mkwsTemplate_Summary` -- used for each summary record in a list of
- results.
-
-* `mkwsTemplate_Record` -- used when displaying a full record.
-
-For both of these the metadata record is passed in, and its fields can
-be referenced in the template. As well as the metadata fields
-(`md-*`), two special fields are provided to the `mkwsTemplate_Summary`
-template, for creating popup links for full records. These are `_id`,
-which must be provided as the `id` attribute of a link tag, and
-`_onclick`, which must be provided as the `onclick` attribute.
-
-For example, an application can install a simple author+title summary
-record in place of the usual one providing the following template:
-
-
-
-For details of Handlebars template syntax, see
-[the online documentation](http://handlebarsjs.com/).
-
-
Responsive design
-----------------
@@ -790,4 +862,4 @@ and .CLASS indicates an instance of a class.
- - -
-Copyright (C) 2013-2014 by Index Data ApS,
+Copyright (C) 2013-2014 Index Data ApS.