` elements with special IDs that
-begin `mkws` can be provided. These are filled in by the MKWS code,
+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 components: a search box and a
-results area. But more are supported. The main `
`s are:
+application above has only two such widgets: a search box and a
+results area. But more are supported.
+
+Defining Widget Elements
+========================
+
+Widget type
+-----------
-* `mkwsSearch` -- provides the search box and button.
+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.
-* `mkwsResults` -- provides the results area, including a list of
+The main widgets are:
+
+* `mkws-search` -- provides the search box and button.
+
+* `mkws-results` -- provides the results area, including a list of
brief records (which open out into full versions when clicked),
paging for large results sets, facets for refining a search,
sorting facilities, etc.
-* `mkwsLang` -- provides links to switch between one of several
- different UI languages. By default, English, Danish and German are
- provided.
+* `mkws-progress` -- shows a progress bar indicating how many of the
+ targets have responded to the search request.
-* `mkwsSwitch` -- provides links to switch between a view of the
+* `mkws-stat` -- provides a status line summarising the statistics of
+ the various targets.
+
+* `mkws-switch` -- provides links to switch between a view of the
result records and of the targets that provide them. Only
meaningful when `mkwsTargets` is also provided.
-* `mkwsTargets` -- the area where per-target information will appear
+* `mkws-targets` -- the area where per-target information will appear
when selected by the link in the `mkwsSwitch` area. Of interest
mostly for fault diagnosis rather than for end-users.
-* `mkwsStat` --provides a status line summarising the statistics of
- the various targets.
+* `mkws-lang` -- provides links to switch between one of several
+ different UI languages. By default, English, Danish and German are
+ provided.
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`. 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
=============
Many aspects of the behaviour of MKWS can be modified by setting
-parameters into the `mkws_config` object. **This must be done *before*
-including the MKWS JavaScript** so that when that code is executed it
-can refer to the configuration values. So the HTML header looks like
-this:
+parameters into the `mkws_config` object. So the HTML header looks
+like this:
+
+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="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, ``.
+
+Templates for MKWS can also be
+[precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled
+template of the same name is found in the `Handlebars.templates` object, it
+will be used instead of the default.
+
+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.
+
+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
+returned by the back end without needing to use a Javascript debugger. For
+example, you might prepend `{{log hits}}` to the Records template in order to
+see what is being returned with each search result in the list. In order for
+this to work you'll need to enable verbose output from Handlebars which is done
+by including this line or similar:
+
+
+
+Internationalisation
+--------------------
-* `mkwsTemplate_Record` -- used when displaying a full record.
+If you would like your template to use the built in translation functionality,
+output locale specific text via the mkws-translate helper like so:
+`{{{mkws-translate "a few words"}}}`.
-For both of these the metadata record is passed in, and its fields can
-be referenced in the template. As well as the metadata fields
-(`md-*`), two special fields are provided to the `mkwsTemplate_Summary`
-template, for creating popup links for full records. These are `_id`,
-which must be provided as the `id` attribute of a link tag, and
-`_onclick`, which must be provided as the `onclick` attribute.
+Example
+-------
-For example, an application can install a simple author+title summary
-record in place of the usual one providing the following template:
+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`:
-
-
-For details of Handlebars template syntax, see
-[the online documentation](http://handlebarsjs.com/).
+ {{#if md-title-remainder}}
+ {{md-title-remainder}}
+ {{/if}}
+ {{#if md-title-responsibility}}
+ {{md-title-responsibility}}
+ {{/if}}
+
+ {{/each}}
+
+For a more involved example where markup for multiple widgets is decorated with
+[Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is
+employed, take a look at the source of
+[topic.html](http://example.indexdata.com/topic.html?q=water).
-Responsive design
------------------
-Metasearching applications may need to appear differently on
-small-screened mobile devices, or change their appearance when
-screen-width changes (as when a small device is rotated). To achieve
-this, MKWS supports responsive design which will move the termlists to
-the bottom on narrow screens and to the sidebar on wide screens.
+Refinements
+===========
-To turn on this behaviour, set the `responsive_design_width` to the desired
-threshhold width in pixels. For example:
-
+Message of the day
+------------------
-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.
+Some applications might like to open with content in the area that
+will subsequently be filled with result-records -- a message of the
+day, a welcome message or a help page. This can be done by placing an
+`mkwsMOTD` division anywhere on the page. It will be moved into the
+`mkwsResults` area and initially displayed, but will be hidden when a
+search is made.
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:
@@ -398,6 +496,14 @@ of this hostname to your library by setting the User Access record's
that this is not secure, as other applications can use this virtual
hostname to gain access to your library.**
+Or if your application's users are coming from a well-known range of
+IP-address space, you can enter the range in the "IP Ranges"
+field. The format of this field is as follows: it can contain any
+number of ranges, separated by commas; each range is either a single
+IP address or two addresses separated by a hyphen; each IP address is
+four small integers separated by periods. For example,
+`80.229.143.255-80.229.143.255, 5.57.0.0-5.57.255.255, 127.0.0.1`.
+
Alternatively, your application can authenticate by username and
password credentials. This is a useful approach in several situations,
including when you need to specify the use of a different library from
@@ -405,22 +511,25 @@ usual one. To arrange for this, set the username and password as a
single string separated by a slash -- e.g. "mike/swordfish" -- into
the User Access record's Authentication field.
-You can create multiple User Access records: for example, one that
-uses Referring URL, and another that uses a username/password pair to
-be used when running an application from a different URL.
+You can set multiple fields into a single User Access record; or
+create multiple User Access records. For example, a single User Access
+record can specify both a Referring URL a username/password pair that
+can be used when running an application from a different URL. But if
+multiple Referring URLs are needed, then each must be specified in its
+own User Access record.
### Tell the application to use the library
In the HTML of the application, tell MKWS to authenticate on to the
-Service Proxy. When IP-based, referer-based or hostname-based
-authentication is used, this is very simple:
+Service Proxy. When referer-based or IP-based authentication is used,
+this is very simple:
-> TODO This should be the default setting
+> TODO This should be the default setting: see **MKWS-251**.
And ensure that access to the MWKS application is from the correct
Referrer URL or IP-range.
@@ -431,13 +540,14 @@ When hostname-based authentication is in use, it's necessary to access
the Service Proxy as the correctly named virtual host. This can be
done by setting the `service_proxy_auth` configuration item to a
URL containing that hostname, such as
-
+`//yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig`
> TODO It should be possible to change just the hostname without
-> needing to repeat the rest of the URL (protocol, path, query)
+> needing to repeat the rest of the URL (protocol, path, query): see
+> **MKWS-252**.
> TODO When changing the SP authentication URL, the Pazpar2 URL should
-> in general change along with it.
+> in general change along with it: see **MKWS-253**.
### (Optional): embed credentials for access to the library
@@ -445,10 +555,11 @@ When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
Proxy when establishing the session. This can most simply be done just
by setting the `service_proxy_auth` configuration item to a URL such as
-
+`//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish`
> TODO It should be possible to add the username and password to the
-> configuration without needing to repeat the rest of the URL.
+> configuration without needing to repeat the rest of the URL: see
+> **MKWS-254**.
### (Optional): conceal credentials from HTML source
@@ -466,15 +577,16 @@ to that local authentication URL. Here is one way to do it when
Apache2 is the application's web-server, which we will call
yourname.com:
-- Add a rewriting authentication alias to the configuration:
+Step 1: add a rewriting authentication alias to the configuration:
RewriteEngine on
- RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
+ RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
+
+Step 2: set the MKWS configuration item `service_proxy_auth` to
+
-- Set the MKWS configuration item `service_proxy_auth` to
-
-- Protect access to the local path
- (e.g. using a .htaccess file).
+Step 3: protect access to the local path
+(e.g. using a `.htaccess` file).
Choosing targets from the library
@@ -606,9 +718,9 @@ structure.
3. [10, 20, 30, 50]
-4. http://mkws.indexdata.com/service-proxy-auth
+4. http://sp-mkws.indexdata.com/service-proxy-auth
-5. http://mkws.indexdata.com/service-proxy/
+5. http://sp-mkws.indexdata.com/service-proxy/
6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
@@ -687,19 +799,19 @@ from that toolkit. The relevant lines are:
----
-Element Type Default Description
--------- ----- --------- ------------
-popup_width string 880 Width of the popup window (if used), in
- pixels.
+Element Type Default Description
+-------- ----- ------- ------------
+popup_width string 880 Width of the popup window (if used), in
+ pixels.
-popup_height string 760 Height of the popup window (if used), in
- pixels.
+popup_height string 760 Height of the popup window (if used), in
+ pixels.
-popup_button string input.mkwsButton (Never change this.)
+popup_button string `input.mkwsButton` (Never change this.)
-popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
+popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
-popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
+popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
----
@@ -709,7 +821,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.
@@ -776,4 +888,4 @@ and .CLASS indicates an instance of a class.
- - -
-Copyright (C) 2013-2014 by IndexData ApS,
+Copyright (C) 2013-2014 Index Data ApS.