projects / mkws-moved-to-github.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
rewritten for IE8, MKWS-309
[mkws-moved-to-github.git] / doc / mkws-manual.markdown
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 712e00d..b920dc8 100644 (file)
--- 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.
 
 
 can be embedded: search-boxes, results areas, target information, etc.
 
 
-Simple Example
+Simple example
 ==============
 
 The following is
 ==============
 
 The following is
@@ -97,7 +97,21 @@ Second, within the HTML body, `<div>` 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
 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.
 
 
 * `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
 `<body>` like so:
 
 To see all of these working together, just put them all into the HTML
 `<body>` like so:
 
-        <div id="mkws-switch"></div>
-        <div id="mkws-lang"></div>
-        <div id="mkws-progress"></div>
-        <div id="mkws-search"></div>
-        <div id="mkws-results"></div>
-        <div id="mkws-targets"></div>
-        <div id="mkws-stat"></div>
+        <div class="mkws-switch"></div>
+        <div class="mkws-lang"></div>
+        <div class="mkws-progress"></div>
+        <div class="mkws-search"></div>
+        <div class="mkws-results"></div>
+        <div class="mkws-targets"></div>
+        <div class="mkws-stat"></div>
 
 The full set of supported widgets is described in the
 reference guide below.
 
 
 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,
+`<div class="mkws-search mkws-team-aux">` 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
 **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
 
 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:
 
         <script type="text/javascript">
           var mkws_config = {
 
         <script type="text/javascript">
           var mkws_config = {
+            lang_options: [ "en", "da" ]
             lang: "da",
             sort_default: "title",
             query_width: 60
             lang: "da",
             sort_default: "title",
             query_width: 60
@@ -163,14 +206,52 @@ like this:
         </script>
         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
         </script>
         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
-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.
 
 
 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:
+
+       <div class="mkws-records" maxrecs="3">
+
+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:
+
+       <div class="mkws-records" data-mkws-maxrecs="3">
+
+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):
+
+       <div class="mkws-lang" data-mkws-config='{ "lang_options": [ "en", "da" ] }'></div>
+
+(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
 =========================
 
 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.
 
 
 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
 =====================
 
 MKWS accesses targets using the Pazpar2 metasearching engine. Although
@@ -586,7 +667,7 @@ attribute as follows:
        <div class="mkwsRecords" targetfilter='categories=news'/>
 
 
        <div class="mkwsRecords" targetfilter='categories=news'/>
 
 
-Reference Guide
+Reference guide
 ===============
 
 Configuration object
 ===============
 
 Configuration object
MasterKey Widget Set