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 a275051..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
@@ -99,7 +99,7 @@ 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.
 
 application above has only two such widgets: a search box and a
 results area. But more are supported.
 
-Defining Widget Elements
+Defining widget elements
 ========================
 
 Widget type
 ========================
 
 Widget type
@@ -141,13 +141,13 @@ 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.
@@ -186,8 +186,11 @@ 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.
 
 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
@@ -195,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
@@ -202,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
 =========================
@@ -405,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
@@ -625,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