+
+Although this works well, HTML validators will consider this element
+acceptable, since the `maxrecs` attribute is not part of the HTML
+schema. However, attributes beginning `data-` are always accepted as
+HTML extensions, much like email headers beginning with
+`X-`. Therefore, the widget set also recognises configuration
+attributes prefixed with `data-mkws-`, so:
+
+
+
+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
=========================
@@ -168,7 +264,7 @@ While it's convenient for simple applications to use a monolithic
`mkwsResults` 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:
+following lower-level widgets provided instead:
* `mkwsTermlists` -- provides the facets
@@ -186,7 +282,8 @@ following lower-level components provided instead:
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.
@@ -209,7 +306,7 @@ 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;).
+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
@@ -219,24 +316,24 @@ 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"`)
+`facet-subjects` rather than `facet`. (So `class="mkws-template-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, ``.
+for example, ``.
Templates for MKWS can also be
[precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled
@@ -249,8 +346,7 @@ 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.
+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
@@ -276,7 +372,7 @@ 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`:
-
-
-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
----------------------------
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:
@@ -378,7 +447,7 @@ authentication tokens (to prevent unauthorised use of subscription
resources). For information on how to do this, see the next section.
-MKWS Target Selection
+MKWS target selection
=====================
MKWS accesses targets using the Pazpar2 metasearching engine. Although
@@ -598,7 +667,7 @@ attribute as follows:
-Reference Guide
+Reference guide
===============
Configuration object
@@ -794,7 +863,7 @@ The structure of the HTML generated by the MKWS widgets
In order to override the default CSS styles provided by the MasterKey Widget
Set, it's necessary to understand that structure of the HTML elements that are
-generated within the components. This knowledge make it possible, for example,
+generated within the widgets. This knowledge make it possible, for example,
to style each `
` with class `term` but only when it occurs inside an
element with ID `#mkwsTermlists`, so as to avoid inadvertently styling other
elements using the same class in the non-MKWS parts of the page.