` 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`. -Configuration -============= +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. + +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 @@ -164,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 ========================= @@ -374,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 @@ -594,7 +667,7 @@ attribute as follows:

-Reference Guide +Reference guide =============== Configuration object diff --git a/examples/htdocs/mike.html b/examples/htdocs/mike.html index f764287..724e2b2 100644 --- a/examples/htdocs/mike.html +++ b/examples/htdocs/mike.html @@ -28,14 +28,14 @@ -