+
+For first form is more convenient; the second is more correct.
+
+Because some configuration items take structured values rather than
+simple strings, they cannot be directly provided by inline
+attributes. To allow for this, the special attribute
+`data-mkws-config`, if provided, is parsed as JSON and its key-value
+pairs set as configuration items for the widget in question. For
+example, the value of `lang_options` is an array of strings specifying
+which of the supported UI languages should be made available. The
+following invocation will limit this list to only English and Danish
+(omitting German):
+
+
+
+(Note that, as JSON requires double quotes around all strings, single
+quotes must be used to contain the entire attribute value.)
+
Control over HTML and CSS
--------------------------
+=========================
-More sophisticated applications will not simply place the `
`s
+More sophisticated applications will not simply place the widgets
together, but position them carefully within an existing page
framework -- such as a Drupal template, an OPAC or a SharePoint page.
While it's convenient for simple applications to use a monolithic
-`mkwsResults` area which contains record, facets, sorting options,
+`mkws-results` area which contains record, facets, sorting options,
etc., customised layouts may wish to treat each of these components
-separately. In this case, `mkwsResults` can be omitted, and the
-following lower-level components provided instead:
+separately. In this case, `mkws-results` can be omitted, and the
+following lower-level widgets provided instead:
-* `mkwsTermlists` -- provides the facets
+* `mkws-termlists` -- provides the facets
-* `mkwsRanking` -- provides the options for how records are sorted and
+* `mkws-ranking` -- provides the options for how records are sorted and
how many are included on each page of results.
-* `mkwsPager` -- provides the links for navigating back and forth
+* `mkws-pager` -- provides the links for navigating back and forth
through the pages of records.
-* `mkwsNavi` -- when a search result has been narrowed by one or more
+* `mkws-navi` -- when a search result has been narrowed by one or more
facets, this area shows the names of those facets, and allows the
selected values to be clicked in order to remove them.
-* `mkwsRecords` -- lists the actual result records.
+* `mkws-records` -- lists the actual result records.
Customisation of MKWS searching widgets can also be achieved by
overriding the styles set in the toolkit's CSS stylesheet. The default
-styles can be inspected in `mkws.css` and overridden in any
+styles can be inspected in [mkws.css](mkws.css)
+and overridden in any
styles that appears later in the HTML than that file. At the simplest
level, this might just mean changing fonts, sizes and colours, but
more fundamental changes are also possible.
@@ -190,102 +294,145 @@ containers. The structures used by the widget-set are described in the
reference guide below.
-Refinements
------------
-
-
-### Message of the day
+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/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`. (So `class="mkws-template-facet-subjects"`.) When
+rendering a facet for which no specific template is defined, the code
+falls back to using the generic facet template, just called `facet`.
+
+You can also explicitly specify a different template for a particular
+instance of a widget by providing the name of your alternative
+(eg. `special-pager`) 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 the 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.
+
+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 toolkit's included AJAX helpers to render record
+details inline, here's a summary 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).
+
+
+Some Refinements
+================
+
+
+Message of the day
+------------------
Some applications might like to open with content in the area that
will subsequently be filled with result-records -- a message of the
day, a welcome message or a help page. This can be done by placing an
-`mkwsMOTD` division anywhere on the page. It will be moved into the
-`mkwsResults` area and initially displayed, but will be hidden when a
-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/).
-
+`mkws-motd` division anywhere on the page. It will initially be moved
+into the `mkws-results` area and displayed, but will be hidden as soon
+as the first search is made.
-### Responsive design
-Metasearching applications may need to appear differently on
-small-screened mobile devices, or change their appearance when
-screen-width changes (as when a small device is rotated). To achieve
-this, MKWS supports responsive design which will move the termlists to
-the bottom on narrow screens and to the sidebar on wide screens.
-
-To turn on this behaviour, set the `responsive_design_width` to the desired
-threshhold width in pixels. For example:
-
-
-
-If individual result-related components are in use in place of the
-all-in-one mkwsResults, then the redesigned application needs to
-specify the locations where the termlists should appear in both
-cases. In this case, wrap the wide-screen `mkwsTermlists` element in a
-`mkwsTermlists-Container-wide` element; and provide an
-`mkwsTermlists-Container-narrow` element in the place where the narrow-screen
-termlists should appear.
-
-
-### Popup results with jQuery UI
+Popup results with jQuery UI
+----------------------------
The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI)
-can be used to construct MKWS applications in which the only component
+can be used to construct MKWS applications in which the only widget
generally visible on the page is a search box, and the results appear
in a popup. The key part of such an application is this invocation of
the MKWS jQuery plugin:
-
-