X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=b920dc860a4010d394d1d492762a83abf6ffe2d8;hb=6cba1240099271c998511cb2bbf607ebe7aed7fc;hp=712e00d30a01ce622992ed7aadffbbb0f4ee911a;hpb=b50413d3892a5a00b64a941ff16272e3f553170b;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 712e00d..b920dc8 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -51,7 +51,7 @@ MKWS classes in any HTML page, the various components of an application
can be embedded: search-boxes, results areas, target information, etc.
-Simple Example
+Simple example
==============
The following is
@@ -97,7 +97,21 @@ Second, within the HTML body, `
` elements with special IDs that
begin `mkws-` can be provided. These are filled in by the MKWS code,
and provide the components of the searching UI. The very simple
application above has only two such widgets: a search box and a
-results area. But more are supported. The main widgets are:
+results area. But more are supported.
+
+Defining widget elements
+========================
+
+Widget type
+-----------
+
+An HTML element is made an MKWS widget by including an MKWS
+class-name. These names begin `mkws-`: what follows that prefix
+specifies the type of the widget. The type can be any sequence of
+alphanumeric characters and hyphens _except_ something beginning
+`team` -- see below.
+
+The main widgets are:
* `mkws-search` -- provides the search box and button.
@@ -127,28 +141,56 @@ results area. But more are supported. The main widgets are:
To see all of these working together, just put them all into the HTML
`` like so:
-
-
-
-
-
-
-
+
+
+
+
+
+
+
The full set of supported widgets is described in the
reference guide below.
+Widget team
+-----------
+
+In general a set of widgets work together in a team: in the example
+above, the search-term that the user enters in the `mkws-search`
+widget is used to generate the set of records that are displayed in
+the `mkws-results` widget.
+
+Sometimes, it's desirable to have multiple teams in a single page. A
+widget can be placed in a named team by giving it (in addition to its
+main class) a class that begins with `mkws-team-`: what follows that
+prefix specifies the team that the widget is part of. For example,
+`
` creates a search widget that
+is part of the `aux` team.
+
+Widgets that do not have a team specified (as in the examples above)
+are placed in the team called `AUTO`.
+
+Old and new-style class-names
+-----------------------------
+
**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. The 1.x series
-of MKWS versions also recognise these old-style class-names as a
-facility for backwards compatibility. However, these **old class-names
-are deprecated, and support will be removed in v2.0**. Existing
-applications that use them should be upgraded to the new-style class
-names as soon as convenient.
+instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
+used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be
+`mkwsTeam_foo`.
+
+The 1.x series of MKWS releases recognise these old-style class-names
+as well as the canonical ones, as a facility for backwards
+compatibility. However, **these old class-names are deprecated, and
+support will be removed in v2.0**. Existing applications that use them
+should be upgraded to the new-style class names as soon as convenient.
-Configuration
-=============
+Configuring widgets
+===================
+
+Global configuration
+--------------------
Many aspects of the behaviour of MKWS can be modified by setting
parameters into the `mkws_config` object. So the HTML header looks
@@ -156,6 +198,7 @@ like this:
-This configuration sets the UI language to Danish (rather than the
-default of English), initially sorts search results by title rather
-than relevance (though as always this can be changed in the UI) and
-makes the search box a bit wider than the default.
+This configuration restricts the set of available UI languages English
+and Danish (omitting German), sets the default to Danish (rather than
+the English), initially sorts search results by title rather than
+relevance (though as always this can be changed in the UI) and makes
+the search box a bit wider than the default.
The full set of supported configuration items is described in the
reference guide below.
+Per-widget configuration
+------------------------
+
+In addition to the global configuration provided by the `mkws_config`
+object, individual widgets' behaviour can be configured by providing
+configuration items as attributed on their HTML elements. For example,
+a `records` widget might be restricted to displaying no more than
+three records by setting the `numrecs` parameter as follows:
+
+
+
+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
=========================
@@ -366,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
@@ -586,7 +667,7 @@ attribute as follows:
-Reference Guide
+Reference guide
===============
Configuration object