Remove trailing whitespace.
[mkws-moved-to-github.git] / doc / mkws-manual.markdown
1 % The MKWS manual: embedded metasearching with the MasterKey Widget Set
2 % Mike Taylor
3 % October 2014
4
5
6 Introduction
7 ============
8
9 There are lots of practical problems in building resource discovery
10 solutions. One of the biggest, and most ubiquitous is incorporating
11 metasearching functionality into existing web-sites -- for example,
12 content-management systems, library catalogues or intranets. In
13 general, even when access to core metasearching functionality is
14 provided by simple web-services such as
15 [Pazpar2](http://www.indexdata.com/pazpar2), integration work is seen
16 as a major part of most projects.
17
18 Index Data provides several different toolkits for communicating with
19 its metasearching middleware, trading off varying degrees of
20 flexibility against convenience:
21
22 * [pz2.js](http://www.indexdata.com/pazpar2/doc/ajaxdev.html) --
23   a low-level JavaScript library for interrogating the
24   [Service Proxy](http://www.indexdata.com/service-proxy/)
25   and
26   [Pazpar2](http://www.indexdata.com/pazpar2/).
27   It allows the HTML/JavaScript programmer
28   to create JavaScript applications to display facets, records,
29   etc. that are fetched from the metasearching middleware.
30
31 * masterkey-ui-core -- a higher-level, complex JavaScript library that
32   uses pz2.js to provide the pieces needed for building a
33   full-featured JavaScript application.
34
35 * MasterKey Demo UI -- an example of a searching application built on
36   top of masterkey-ui-core. Available as a public demo at
37   <http://mk2.indexdata.com/>
38
39 * [MKDru](http://www.indexdata.com/masterkey-drupal) --
40   a toolkit for embedding MasterKey-like searching into
41   [Drupal](https://www.drupal.org/)
42   sites.
43
44 All but the last of these approaches require programming to a greater or lesser
45 extent. Against this backdrop, we introduced
46 [MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
47 -- a set of simple, very high-level HTML+CSS+JavaScript
48 components that can be incorporated into any web-site to provide
49 MasterKey searching facilities. By placing `<div>`s with well-known
50 MKWS classes in any HTML page, the various components of an application
51 can be embedded: search-boxes, results areas, target information, etc.
52
53
54 Simple example
55 ==============
56
57 The following is
58 [a complete MKWS-based searching application](//example.indexdata.com/simple.html):
59
60         <html>
61           <head>
62             <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
63             <title>MKWS demo client</title>
64             <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
65             <link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
66           </head>
67           <body>
68             <div class="mkws-search"></div>
69             <div class="mkws-results"></div>
70           </body>
71         </html>
72
73 Go ahead, try it! Simply put the above in a file (e.g index.html),
74 drop it into a folder accessible with an ordinary web-server (e.g
75 Apache) and load it in your web browser. Just like that, you have
76 working metasearching.
77
78 How the example works
79 ---------------------
80
81 If you know any HTML, the structure of the file will be familar to
82 you: the `<html>` element at the top level contains a `<head>` and a
83 `<body>`. In addition to whatever else you might want to put on your
84 page, you can add MKWS elements.
85
86 These fall into two categories. First, the prerequisites in the HTML
87 header, which are loaded from the tool site `mkws.indexdata.com`:
88
89 * `mkws-complete.js`
90   contains all the JavaScript needed by the widget-set, including a
91   copy of the jQuery library.
92
93 * `mkws.css`
94   provides the default CSS styling
95
96 Second, within the HTML body, `<div>` elements with special IDs that
97 begin `mkws-` can be provided. These are filled in by the MKWS code,
98 and provide the components of the searching UI. The very simple
99 application above has only two such widgets: a search box and a
100 results area. But more are supported.
101
102 Defining widget elements
103 ========================
104
105 Widget type
106 -----------
107
108 An HTML element is made an MKWS widget by including an MKWS
109 class-name. These names begin `mkws-`: what follows that prefix
110 specifies the type of the widget. The type can be any sequence of
111 alphanumeric characters and hyphens _except_ something beginning
112 `team` -- see below.
113
114 The main widgets are:
115
116 * `mkws-search` -- provides the search box and button.
117
118 * `mkws-results` -- provides the results area, including a list of
119    brief records (which open out into full versions when clicked),
120    paging for large results sets, facets for refining a search,
121    sorting facilities, etc.
122
123 * `mkws-progress` -- shows a progress bar indicating how many of the
124    targets have responded to the search request.
125
126 * `mkws-stat` -- provides a status line summarising the statistics of
127    the various targets.
128
129 * `mkws-switch` -- provides links to switch between a view of the
130    result records and of the targets that provide them. Only
131    meaningful when `mkws-targets` is also provided.
132
133 * `mkws-targets` -- the area where per-target information will appear
134    when selected by the link in the `mkws-switch` area. Of interest
135    mostly for fault diagnosis rather than for end-users.
136
137 * `mkws-lang` -- provides links to switch between one of several
138    different UI languages. By default, English, Danish and German are
139    provided.
140
141 To see all of these working together, just put them all into the HTML
142 `<body>` like so:
143
144         <div class="mkws-switch"></div>
145         <div class="mkws-lang"></div>
146         <div class="mkws-progress"></div>
147         <div class="mkws-search"></div>
148         <div class="mkws-results"></div>
149         <div class="mkws-targets"></div>
150         <div class="mkws-stat"></div>
151
152 The full set of supported widgets is described in the
153 reference guide
154 [below](#widgets).
155
156 Widget team
157 -----------
158
159 In general a set of widgets work together in a team: in the example
160 above, the search-term that the user enters in the `mkws-search`
161 widget is used to generate the set of records that are displayed in
162 the `mkws-results` widget.
163
164 Sometimes, it's desirable to have multiple teams in a single page. A
165 widget can be placed in a named team by giving it (in addition to its
166 main class) a class that begins with `mkws-team-`: what follows that
167 prefix specifies the team that the widget is part of. For example,
168 `<div class="mkws-search mkws-team-aux">` creates a search widget that
169 is part of the `aux` team.
170
171 Widgets that do not have a team specified (as in the examples above)
172 are placed in the team called `AUTO`.
173
174 Configuring widgets
175 ===================
176
177 Global configuration
178 --------------------
179
180 Many aspects of the behaviour of MKWS can be modified by setting
181 parameters into the `mkws_config` object. So the HTML header looks
182 like this:
183
184         <script type="text/javascript">
185           var mkws_config = {
186             lang_options: [ "en", "da" ]
187             lang: "da",
188             sort_default: "title",
189           };
190         </script>
191         <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
192
193 This configuration restricts the set of available UI languages English
194 and Danish (omitting German), sets the default to Danish (rather than
195 the English), and initially sorts search results by title rather than
196 relevance (though as always this can be changed in the UI).
197
198 The full set of supported configuration settings is described in the
199 reference guide below.
200
201 Per-widget configuration
202 ------------------------
203
204 In addition to the global configuration provided by the `mkws_config`
205 object, individual widgets' behaviour can be configured by providing
206 configuration settings as attributes on their HTML elements. For example,
207 a `records` widget might be restricted to displaying no more than
208 three records by setting the `numrecs` parameter as follows:
209
210         <div class="mkws-records" maxrecs="3">
211
212 Although this works well, HTML validators will consider this element
213 acceptable, since the `maxrecs` attribute is not part of the HTML
214 schema. However, attributes beginning `data-` are always accepted as
215 HTML extensions, much like email headers beginning with
216 `X-`. Therefore, the widget set also recognises configuration
217 attributes prefixed with `data-mkws-`, so:
218
219         <div class="mkws-records" data-mkws-maxrecs="3">
220
221 For first form is more convenient; the second is more correct.
222
223 Because some configuration settings take structured values rather than
224 simple strings, they cannot be directly provided by inline
225 attributes. To allow for this, the special attribute
226 `data-mkws-config`, if provided, is parsed as JSON and its key-value
227 pairs used as configuration settings for the widget in question. For
228 example, the value of `lang_options` is an array of strings specifying
229 which of the supported UI languages should be made available. The
230 following invocation will limit this list to only English and Danish
231 (omitting German):
232
233         <div class="mkws-lang" data-mkws-config='{ "lang_options": [ "en", "da" ] }'></div>
234
235 (Note that, as JSON requires double quotes around all strings, single
236 quotes must be used to contain the entire attribute value.)
237
238
239 Control over HTML and CSS
240 =========================
241
242 More sophisticated applications will not simply place the widgets
243 together, but position them carefully within an existing page
244 framework -- such as a Drupal template, an OPAC or a SharePoint page.
245
246 While it's convenient for simple applications to use a monolithic
247 `mkws-results` area which contains record, facets, sorting options,
248 etc., customised layouts may wish to treat each of these components
249 separately. In this case, `mkws-results` can be omitted, and the
250 following lower-level widgets provided instead:
251
252 * `mkws-facets` -- provides the facets
253
254 * `mkws-ranking` -- provides the options for how records are sorted and
255    how many are included on each page of results.
256
257 * `mkws-pager` -- provides the links for navigating back and forth
258    through the pages of records.
259
260 * `mkws-navi` -- when a search result has been narrowed by one or more
261    facets, this area shows the names of those facets, and allows the
262    selected values to be clicked in order to remove them.
263
264 * `mkws-records` -- lists the actual result records.
265
266 Customisation of MKWS searching widgets can also be achieved by
267 overriding the styles set in the toolkit's CSS stylesheet. The default
268 styles can be inspected in [mkws.css](mkws.css)
269 and overridden in any
270 styles that appears later in the HTML than that file. At the simplest
271 level, this might just mean changing fonts, sizes and colours, but
272 more fundamental changes are also possible.
273
274 To properly apply styles, it's necessary to understand how the HTML is
275 structured, e.g. which elements are nested within which
276 containers. The structures used by the widget-set are described in the
277 reference guide below.
278
279
280 Customised display using Handlebars templates
281 =============================================
282
283 A lot can be done by styling widgets in CSS and changing basic MKWS config
284 options. For further customisation, MKWS allows you to change the markup it
285 outputs for any widget. This is done by overriding the
286 [Handlebars](http://handlebarsjs.com/) template used to generate it. In general
287 these consist of `{{things in double braces}}` that are replaced by values from
288 the system. For details of Handlebars template syntax, see [the online
289 documentation](http://handlebarsjs.com/).
290
291 The templates used by the core widgets can be viewed in [our git
292 repository](http://git.indexdata.com/?p=mkws.git;a=tree;f=src/templates;).
293 Parameters are documented in a comment at the top of each template so
294 you can see what's going where. If all you want to do is add a CSS class to
295 something or change a `span` to a `div` it's easy to just copy the existing
296 template and make your edits.
297
298 Overriding templates
299 --------------------
300
301 To override the template for a widget, include it inline in the document
302 as a `<script>` tag marked with a class of `mkws-template-foo` where foo is the
303 name of the template you want to override (typically the name of the widget).
304 Inline Handlebars templates are distinguished from Javascript via a
305 `type="text/x-handlebars-template"` attribute. For example, to override the
306 pager template you would include this in your document:
307
308         <script class="mkws-template-pager" type="text/x-handlebars-template">
309           ...new Pager template
310         </script>
311
312 The Facet template has a special feature where you can override it on
313 a per-facet basis by adding a dash and the facet name as a suffix eg.
314 `facet-subjects`. (So `class="mkws-template-facet-subjects"`.) When
315 rendering a facet for which no specific template is defined, the code
316 falls back to using the generic facet template, just called `facet`.
317
318 You can also explicitly specify a different template for a particular
319 instance of a widget by providing the name of your alternative
320 (eg. `special-pager`) as the value of the `template` key in the MKWS
321 config object for that widget: for example, `<div class="mkws-pager"
322 template="special-pager"/>`.
323
324 Templates for MKWS can also be
325 [precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled
326 template of the same name is found in the `Handlebars.templates` object, it
327 will be used instead of the default.
328
329 Inspecting metadata for templating
330 ----------------------------------
331
332 MKWS makes requests to the Service Proxy or Pazpar2 that perform the
333 actual searching. Depending on how these are configured and what is
334 available from the targets you are searching there may be more data
335 available than what is presented by the default templates.
336
337 Handlebars offers a convenient log helper that will output the contents of a
338 variable for you to inspect. This lets you look at exactly what is being
339 returned by the back end without needing to use a Javascript debugger. For
340 example, you might prepend `{{log hits}}` to the Records template in order to
341 see what is being returned with each search result in the list. In order for
342 this to work you'll need to enable verbose output from Handlebars which is done
343 by including this line or similar:
344
345         <script>Handlebars.logger.level = 1;</script>
346
347 Internationalisation
348 --------------------
349
350 If you would like your template to use the built in translation functionality,
351 output locale specific text via the mkws-translate helper like so:
352 `{{{mkws-translate "a few words"}}}`.
353
354 Example
355 -------
356
357 Rather than use the toolkit's included AJAX helpers to render record
358 details inline, here's a summary template that will link directly to
359 the source via the address provided in the metadata as the first
360 element of `md-electronic-url`:
361
362         <script class="mkws-template-summary" type="text/x-handlebars-template">
363           <a href="{{md-electronic-url.[0]}}">
364             <b>{{md-title}}</b>
365           </a>
366           {{#if md-title-remainder}}
367             <span>{{md-title-remainder}}</span>
368           {{/if}}
369           {{#if md-title-responsibility}}
370             <span><i>{{md-title-responsibility}}</i></span>
371           {{/if}}
372         </script>
373
374 For a more involved example where markup for multiple widgets is decorated with
375 [Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is
376 employed, take a look at the source of
377 [topic.html](http://example.indexdata.com/topic.html?q=water).
378
379
380 Some Refinements
381 ================
382
383
384 Message of the day
385 ------------------
386
387 Some applications might like to open with content in the area that
388 will subsequently be filled with result-records -- a message of the
389 day, a welcome message or a help page. This can be done by placing an
390 `mkws-motd` division anywhere on the page. It will initially be moved
391 into the `mkws-results` area and displayed, but will be hidden as soon
392 as the first search is made.
393
394
395 Popup results with jQuery UI
396 ----------------------------
397
398 The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI)
399 can be used to construct MKWS applications in which the only widget
400 generally visible on the page is a search box, and the results appear
401 in a popup. The key part of such an application is this invocation of
402 the MKWS jQuery plugin:
403
404         <div class="mkws-search"></div>
405         <div class="mkws-popup" popup_width="1024" popup_height="650">
406           <div class="mkws-results"></div>
407         </div>
408
409 The necessary scaffolding can be seen in an example application,
410 [popup.html](http://example.indexdata.com/popup.html).
411
412 The relevant properties (`popup_width`, etc.) are documented
413 [below](#jquery-ui-popup-invocation)
414 in the reference section.
415
416
417 MKWS target selection
418 =====================
419
420 Introduction
421 ------------
422
423 MKWS accesses targets using the Pazpar2 metasearching engine. Although
424 Pazpar2 can be used directly, using a statically configured set of
425 targets, this usage is unusual. More often, Pazpar2 is fronted by the
426 Service Proxy (SP), which manages authentication, sessions, target
427 selection, etc. This document assumes the SP is used, and explains how
428 to go about making a set of targets (a "library") available, how to
429 connect your MKWS application to that library, and how to choose which
430 of the available targets to use.
431
432 By default MKWS configures itself to use an account on a service
433 hosted by `sp-mkws.indexdata.com`. By default, it sends no
434 authentication credentials, allowing the appropriate account to be
435 selected on the basis of referring URL or IP address.
436
437 If no account has been set up to recognise the referring URL of the
438 application or the IP address of the client, then a default "MKWS
439 Demo" account is used. This account (which can also be explicitly
440 chosen by using the username `mkws`, password `mkws`) provides access
441 to about a dozen free data sources.
442
443 In order to search in a customised set of targets, including
444 subscription resources, it's necessary to create an account with
445 Index Data's hosted Service Proxy, and protect that account with
446 authentication tokens (to prevent unauthorised use of subscription
447 resources).
448
449 Maintaining the library
450 -----------------------
451
452 The Service Proxy accesses sets of targets that are known as
453 "libraries". In general, each customer will have their own library,
454 though some standard libraries may be shared between many customers --
455 for example, a library containing all open-access academic journals.
456 A library can also contain other configuration information, including
457 the set of categories by which targets are classified for the library.
458
459 Libraries are maintained using MKAdmin (MasterKey
460 Admin). Specifically, those used by MKWS are generally maintained on
461 the "MKX Admin" installation at
462 <http://mkx-admin.indexdata.com/console/>
463 In general, Index Data will create a library for each customer, then
464 give the customer a username/password pair that they can use to enter
465 MKAdmin and administrate that library.
466
467 Once logged in, customers can select which targets to include (from
468 the list of several thousand that MKAdmin knows about), and make
469 customer-specific modifications to the target profiles --
470 e.g. overriding the titles of the targets.
471
472 Most importantly, customers' administrators can add authentication
473 credentials that the Service Proxy will use on their behalf when
474 accessing subscription resources -- username/password pairs or proxies
475 to use for IP-based authentication. Note that **it is then crucial to
476 secure the library from use by unauthorised clients**, otherwise the
477 customer's paid subscriptions will be exploited.
478
479 Access to libraries is managed by creating one or more "User Access"
480 records in MKAdmin, under the tab of that name. Each of these records
481 provides a combination of credentials and other data that allow an
482 incoming MKWS client to be identified as having legitimate access to
483 the library. The authentication process, described below, works by
484 searching for a matching User Access record.
485
486
487 Authenticating your MWKS application onto the library
488 -----------------------------------------------------
489
490 Some MKWS applications will be content to use the default library with
491 its selection of targets. Most, though, will want to define their own
492 library providing a different range of available targets. An important
493 case is that of applications that authenticate onto subscription
494 resources by means of back-end site credentials stored in MKAdmin:
495 precautions must be taken so that such library accounts do not allow
496 unauthorised access.
497
498 Setting up such a library is a process of several stages.
499
500 ### Create the User Access account
501
502 Log in to MKAdmin to add a User Access account for your library:
503
504 * Go to <http://mkx-admin.indexdata.com/console/>
505 * Enter the adminstrative username/password
506 * Go to the User Access tab
507 * Create an end-user account
508 * Depending on what authentication method it be used, set the
509   User Access account's username and password, or referring URL, or
510   IP-address range.
511
512 If your MWKS application runs at a well-known, permanent address --
513 <http://yourname.com/app.html>, say -- you can set the User Access
514 record so that this originating URL is recognised by setting it into
515 the "Referring URL" field. Then the application will always use that
516 library that this User Access record is associated with (unless it
517 sends a username/password pair to override this default).
518
519 Or if your application's users are coming from a well-known range of
520 IP-address space, you can enter the range in the "IP Ranges"
521 field. The format of this field is as follows: it can contain any
522 number of ranges, separated by commas; each range is either a single
523 IP address or two addresses separated by a hyphen; each IP address is
524 four small integers separated by periods. For example,
525 `80.229.143.255-80.229.143.255, 5.57.0.0-5.57.255.255, 127.0.0.1`.
526
527 Alternatively, your application can authenticate by username and
528 password credentials. This is a useful approach in several situations,
529 including when you need to specify the use of a different library from
530 usual one. To arrange for this, set the username and password as a
531 single string separated by a slash -- e.g. `mike/swordfish` -- into
532 the User Access record's Authentication field.
533
534 You can set multiple fields into a single User Access record; or
535 create multiple User Access records. For example, a single User Access
536 record can specify both a Referring URL and a username/password pair
537 that can be used when running an application from a different URL. But
538 if multiple Referring URLs are needed, then each must be specified in
539 its own User Access record.
540
541 ### (Optional): embed credentials for access to the library
542
543 When credential-based authentication is in use (username and
544 password), it's necessary to pass these credentials into the Service
545 Proxy when establishing the session. This is done
546 by providing the `sp_auth_credentials` configuration setting as a string
547 containing the username and password separated by a slash:
548
549         mkws_config = { sp_auth_credentials: "mike/swordfish" };
550
551 ### (Optional): conceal credentials from HTML source
552
553 Using credential-based authentication settings such as those above
554 reveals the the credentials to public view -- to anyone who does View
555 Source on the MKWS application. This may be acceptable for some
556 libraries, but is intolerable for those which provide authenticated
557 access to subscription resources.
558
559 In these circumstances, a different approach is
560 necessary. Referer-based or IP-based authentication may be
561 appropriate. But if these are not possible, then a more elaborate
562 approach can be used to hide the credentials in a web-server
563 configuration that is not visible to users.
564
565 The idea is to make a Service Proxy authentication URL local to the
566 customer, hiding the credentials in a rewrite rule in the local
567 web-server's configuration. Then local mechanisms can be used to limit
568 access to that local authentication URL. Here is one way to do it when
569 Apache2 is the application's web-server, which we will call
570 yourname.com`:
571
572 Step 1: add a rewriting authentication alias to the configuration:
573
574         RewriteEngine on
575         RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/\
576                 ?command=auth&action=check,login&username=U&password=PW [P]
577
578 Step 2: set the MKWS configuration setting `service_proxy_auth` to
579 `http://yourname.com/spauth/`.
580
581 Step 3: protect access to the local path `http://yourname.com/spauth/`
582 (e.g. using a `.htaccess` file).
583
584
585 Choosing targets from the library
586 ---------------------------------
587
588 MKWS applications can choose what subset of the library's targets to
589 use, by means of several alternative settings on individual widgets or
590 in the `mkws_config` structure:
591
592 * `targets` -- contains a Pazpar2 targets string, typically of the form
593   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
594   target IDs.
595   At present, these IDs can take one of two forms, depending on the
596   configuration of the Service Proxy being used: they may be based on
597   ZURLs (so a typical value would be something like
598   `pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902`)
599   or they may be UDBs (so a typical value would be something like
600   `pz:id=brown|artstor`)
601
602 * `targetfilter` -- contains a CQL query which is used to find relevant
603   targets from the relvant library. For example,
604   `udb==Google_Images`
605   or
606   `categories=news`
607
608 * `target` -- contains a single UDB, that of the sole target to be
609   used. For example,
610   `Google_Images`.
611   This is merely syntactic sugar for "targetfilter" with the query
612   `udb==NAME`
613
614 For example, a `Records` widget can be limited to searching only in
615 targets that have been categorised as news sources by providing an
616 attribute as follows:
617
618         <div class="mkws-records" targetfilter='categories=news'/>
619
620
621 Reference guide
622 ===============
623
624 Widgets
625 -------
626
627 The following widgets are provided in the core set. (Others can be
628 added: see the [MKWS developers' guide](mkws-developer.html).)
629
630 ----
631 Name              Description
632 ----              -----------
633 `auth-name`       Initially empty, it updates itself to shows the name
634                   of the library that the application is logged in as
635                   when authentication is complete.
636
637 `builder`         A button which, when pressed, analyses the current
638                   settings of the team that it is a part of, and
639                   generates the HTML for an auto-searching element
640                   that will replicate the present search. This HTML is
641                   displayed in an alert box: it is intended that this
642                   widget be subclassed to store the generated widget
643                   definitions in more useful places.
644
645 `button`          The search button. Usually generated a `search`
646                   widget.
647
648 `categories`      Obtains from the Service Proxy a list of the target
649                   categories associated with the library in use, and
650                   displays them in a drop-down list. When a category
651                   is selected, searches are limited to the targets
652                   that are part of that category.
653
654 `config`          This widget has no functionality of its own, but its
655                   configuration is copied up into its team, allowing
656                   it to affect other widgets in the team. This is the
657                   only way to set configuration settings at the team
658                   level.
659
660 `console-builder` Like the `builder` widget, but emits the generated
661                   HTML on the JavaScript console. This exists to
662                   provide an example of how to subclass the `builder`
663                   widget.
664
665 `cover-art`       Displays cover art for a book by searching in
666                   Amazon. Often used with an `autosearch` attribute to
667                   indicate what book to display. For example,
668                   `<div class="mkws-cover-art" autosearch="isbn=1291177124"></div>`
669                   displays cover art for _All Yesterdays: Unique and
670                   Speculative Views of Dinosaurs and Other Prehistoric
671                   Animals_.
672                   For this widget to work, a library that includes the
673                   AmazonBooks target must be used. For example, the
674                   "DEMO AmazonBooks for MKWS" account, which can be
675                   selected with `sp_auth_credentials="mkws-amazon/mkws"`.
676
677 `details`         This widget is generated by the toolkit itself to
678                   hold the full details of records that are initially
679                   listed in summary form.
680
681 `done`            Initially empty, this widget is set to display
682                   "Search complete: found _n_ records" when all
683                   targets have completed their work, either returning
684                   a hit-count or an error. The message displayed can
685                   be changed by overriding the `done` template using
686                   `<script class="mkws-template-done" type="text/x-handlebars-template">`.
687
688 `facet`           A facet that displays the frequency with which a set
689                   of terms occur within a specific field. The specific
690                   field whose contents are analysed must be specified
691                   by the widget's `facet` configuration setting, which
692                   may conveniently be done by means of the
693                   `data-mkws-facet` attribute on the HTML
694                   element. The supported facets are "subject",
695                   "author" and "xtargets" -- the latter a special case
696                   which treats the target providing a record as a
697                   facet. Most often, `facet` widgets are generated
698                   by a `facets` widget, which knows which facets are
699                   required, but they can also be placed individually.
700
701 `facets`          An area that contains a "Facets" heading and several
702                   `facet` widgets. The set of facet widgets generated
703                   is specified by the `facets` configuration setting,
704                   which may be set globally or at the level of the
705                   widget or the team. The value of this configuration
706                   setting is an array of zero or more strings, each
707                   naming a facet.
708
709 `google-image`    A specialisation of the `images` widget which
710                   defaults to the `Google_Images` target.
711
712 `images`          A specialisation of the `records` widget which
713                   defaults to the `images` template. Unlike the default
714                   summary template, this displays an image from the
715                   URL specified by the `md-thumburl` field of each
716                   record.
717
718 `lang`            Provides a selection between the supported set of
719                   languages (which defaults to English, German and
720                   Danish, but can be configured by the `lang`
721                   configuration setting, whose value is an array of
722                   two-letter language codes).
723
724 `log`             Initially empty, this widget accumulates a log of
725                   messages generated by the widget set, similar to
726                   those emitted on the JavaScript console.
727
728 `lolcat`          A specialisation of the `google-image` widget which
729                   defaults to the search-term "kitteh" and
730                   auto-executes.
731
732 `motd-container`  An empty container which the `motd` widget, if any,
733                   is moved into for initial display. Usually generated
734                   as part of the `results` widget.
735
736 `motd`            May be provided, containing content to appear in the
737                   area where records will later appear. It is moved
738                   into this area (the `motd-container` widget) and
739                   initially displayed; then hidden when the first
740                   search is run. It can be used to provide a "message
741                   of the day".
742
743 `navi`            Shows a list of the facets that have been selected,
744                   and allows them to be deselected.
745
746 `pager`           Shows a list of the available pages of results, and
747                   allows the user to navigate to a selected page.
748
749 `per-page`        Provides a dropdown allowing the user to choose how
750                   many records should appear on each page. The
751                   available set of page-sizes can be specified as the
752                   `perpage_options` configuration setting, whose value is
753                   an array of integers. The initial selected value can
754                   be specified by the `perpage_default` configuration setting.
755
756 `progress`        Shows a progress bar which indicates how many of the
757                   targets have responded to the search.
758
759 `query`           The input area for a query. Usually generated a `search`
760                   widget.
761
762 `ranking`         The result-ranking area, consisting of a `sort`
763                   widget and a `per-page` widget. These may instead
764                   be specified separately if preferred.
765
766 `record`          A detailed display of a single record, usually
767                   appearing when the user clicks on a summary
768                   record. This is generated by the `records` widget.
769
770 `records`         The area in which summary records appear. (Clicking
771                   on a summary record make it pop up as a detailed
772                   record.)
773
774 `reference`       A short summary about a subject specified by the
775                   `autosearch` configuration setting. This is created by
776                   drawing a picture and a paragraph of text from
777                   Wikipedia. To work correctly, this widget must be
778                   used in a library that provides the
779                   `wikimedia_wikipedia_single_result` target.
780
781 `results`         A large compound widget used to provide the most
782                   important results-oriented widgets in a pre-packaged
783                   framework: `facets`, `ranking`, `pager`, `navi` and
784                   `records`.
785
786 `search-form`     The search form, containing the query area and the
787                   button. Usually generated a `search` widget.
788
789 `search`          The search box, consisting of a form containing a
790                   query area and a button.
791
792 `sort`            Provides a dropdown allowing the user to choose how
793                   the displayed records should be sorted. The
794                   available set of sort criteria can be specified as the
795                   `sort_options` configuration setting, whose value is
796                   an array of two-element arrays. The first item of
797                   each sub-array is a pazpar2 sort-expression such as
798                   `data:0` and the second is a human-readable label
799                   such as `newest`. The initial selected
800                   value can be specified by the `sort_default` configuration
801                   setting.
802
803 `stat`            A summary line stating how many targets remain
804                   active, how many records have been found, and how
805                   many of them have been retrieved for display. For
806                   most purposes, the `progress` widget may be
807                   preferable.
808
809 `summary`         A short record, included in the list shown when a
810                   search is run. When clicked, this generally pops up
811                   a detailed `record` widget. This widget is generated
812                   by the toolkit in response to search results.
813
814 `switch`          A pair of buttons allowing the user to switch
815                   between viewing the search results (the usual case)
816                   or the target list.
817
818 `targets`         A list of all targets in the present library,
819                   showing their ID, the number of records they have
820                   found for the current search, any diagnostics they
821                   have returned, the number of records that have been
822                   returned for display, and the connection state.
823 ----
824
825
826 Configuration settings
827 ----------------------
828
829 Configuration settings may be provided at the level of a indiviual widget, or a team, or globally. Per-widget configuration is
830 described above; per-team settings can be placed in a `config` widget belonging to the relevant team, and will be applied to that
831 team as a whole; and global settings are provided in the global variable `mkws_config`. This structure is a key-value lookup
832 table, and may specify the values of many settings.
833
834 Some settings apply only to specific widgets; others to the behaviour of the tookit as a whole. When a widget does not itself have
835 a value specified for a particular configuration setting, its team is consulted; and if that also does not have a value, the global
836 settings are consulted. Only if this, too, is unspecified, is the default value used.
837
838 The supported configuration settings are described in the table below. For those settings that apply only to particular widgets,
839 the relevant widgets are listed. All entries are optional, but if specified must be given values of the specified type. Long
840 default values are in footnotes to keep the table reasonably narrow.
841
842 ----
843 Element                   Widget    Type    Default   Description
844 --------                  ------    -----   --------- ------------
845 autosearch                facet,    string            If provided, this setting contains a query which is immediately run on behalf
846                           facets,                     of the team. Often used with an [indirect setting](#indirect-settings).
847                           record,
848                           records,
849                           results
850
851 facet                     facet     string            For a `facet` widget, this setting is mandatory, and indicates which field to
852                                                       list terms for. Three fields are supported: `subject`, `author` and
853                                                       `xtargets` -- the latter a special case which treats the target providing a
854                                                       record as a facet. Any other field may also be used, but the default caption
855                                                       and maximum term-count may not be appropriate, needing to be overridden by
856                                                       `facet_caption_*` and `facet_max_*` settings.
857
858 facet_caption_*           facet     string            Specifies what on-screen caption is to be used for the named facet: for
859                                                       example, if a `date` facet is generated, then `facet_caption_date` can be
860                                                       used to set the caption to "Year".
861
862 facet_max_*               facet     int               Specifies how many terms are to be displayed for the named facet: for
863                                                       example, if a `publisher` facet is generated, then `facet_max_publisher` can
864                                                       be used to limit the list to the top six.
865
866 facets                    _team_    array   *Note 1*  Ordered list of names of facets to display.
867
868 lang                      _team_    string            The code of the default language to display the UI in. Supported
869                                                       language codes are `en` = English, `de` = German, `da` = Danish, and whatever
870                                                       additional languages are configured using `language_*` entries (see below).
871
872 lang_options              lang      array   []        A list of the languages to offer as options. If empty (the default), then all
873                                                       configured languages are listed.
874
875 language_*                _global_  hash              Support for any number of languages can be added by providing entries whose
876                                                       name is `language_` followed by the code of the language. See the separate
877                                                       section below for details.
878
879 limit                     facet,    string            Allows a partial search to be included in the specification of an
880                           facets,                     auto-executing widget. This is ANDed with the submitted query, as though it
881                           record,                     had been selected from a facet. See the Search section in [the Protocol
882                           records,                    chapter of the Pazpar2 manual
883                           results                     ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
884
885 log_level                 _global_  int     1         Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
886                                                       datestamps, 3 = messages with datestamps and stack-traces.
887
888 maxrecs                   facet,    int               Limits the metasearching middleware to retrieving no more than the specified
889                           facets,                     number of records from each target.
890                           record,
891                           records,
892                           results
893
894 paragraphs                reference int               Limits the number of paragraphs rendered to the specified number. If
895                                                       omitted, there is no limit.
896
897 pazpar2_url               _global_  string            If specified, this is the URL used to access the metasearch middleware. This
898                                                       service must be configured to provide search results, facets, etc. It may be
899                                                       either unmediated Pazpar2 or the MasterKey Service Proxy, which mediates
900                                                       access to an underlying Pazpar2 instance. When not specified, the URL is
901                                                       assembled from `pp2_hostname` and `pp2_path`. See the [Assembling Pazpar2
902                                                       URLs](#assembling-pazpar2-urls) section below.
903
904 perpage                   facet,    int               Specifies the number of records to show per page in an auto-executing
905                           facets,                     widget. Contrast with `perpage_default`, which is used to prime the dropdown
906                           record,                     with which a user chooses the page-size in an interactive session.
907                           records,
908                           results
909
910 perpage_default           _team_    string  20        The initial value for the number of records to show on each page.
911
912 perpage_options           ranking   array   *Note 2*  A list of candidate page sizes. Users can choose between these to determine
913                                                       how many records are displayed on each page of results.
914
915 pp2_hostname              _global_  string  *Note 3*  Unless overridden by the `pazpar2_url` setting, this is used together with
916                                                       `pp2_path` to construct the URL to the Pazpar2 service (or Service
917                                                       Proxy). Set this to connect to a service on a different host from the
918                                                       default.
919
920 pp2_path                  _global_  string  *Note 4*  Unless overridden by the `pazpar2_url` setting, this is used together with
921                                                       `pp2_hostname` to construct the URL to the Pazpar2 service (or Service
922                                                       Proxy). Set this to connect to a service on a different host from the
923                                                       default.
924
925 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
926                                                       widgets. If set to true, a different approach is used which may be faster
927                                                       under some circumstances.
928
929 sentences                 reference int               Limits the number of sentences rendered to the specified number. If
930                                                       omitted, there is no limit.
931
932 service_proxy_auth        _global_  url               If defined, this is the URL which, when `use_service_proxy` is true, is
933                                                       fetched once at the beginning of each session to authenticate the user and
934                                                       establish a session that encompasses a defined set of targets to search
935                                                       in. When not defined, the URL is assembled from `sp_auth_hostname` or
936                                                       `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and
937                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
938                                                       URLs](#assembling-pazpar2-urls) section below.
939
940 service_proxy_auth_domain _global_  domain            When the server used for authentication -- e.g. the one identified by the
941                                                       `service_proxy_auth` URL -- proxies for different server, this can be set to
942                                                       the domain of the server that it proxies for, so that cookies are rewritten
943                                                       to appear to be from this domain.
944
945 show_lang                lang       bool    true      Indicates whether or not to display the language menu.
946
947 show_perpage             ranking    bool    true      Indicates whether or not to display the perpage menu.
948
949 show_sort                ranking    bool    true      Indicates whether or not to display the sort menu.
950
951 show_switch              switch     bool    true      Indicates whether or not to display the switch menu.
952
953 sort                      facet,    string            Specifies the order in which to sort the records retrieved by an
954                           facets,                     auto-executing widget. Must be one of those in the `sort_options`
955                           record,                     array. Contrast with `sort_default`, which is used to prime the dropdown
956                           records,                    with which a user chooses the sortorder in an interactive session.
957                           results
958
959 sort_default              _team_    string  relevance The default sort criterion to use. Must be one of those in the
960                                                       `sort_options` array.
961
962 sort_options              ranking   array   *Note 5*  List of supported sort criteria. Each element of the list is itself a
963                                                       two-element list: the first element of each sublist is a pazpar2
964                                                       sort-expression such as `data:0` and the second is a human-readable label
965                                                       such as `newest`.
966
967 sp_auth_credentials       _global_  string            If defined, this must be a slash-separated combination of username and
968                                                       password, which is sent as the authentication credentials on session
969                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
970                                                       section below.
971
972 sp_auth_hostname          _global_  string            If provided, overrides the `pp2_hostname` setting when constructing the
973                                                       Service Proxy authentication URL. This need only be used when authentication
974                                                       is performed on a different host from the remaining operations (search,
975                                                       retrieve, etc.)
976
977 sp_auth_path              _global_  string            Part of the URL used for authentication. See the [Assembling Pazpar2
978                                                       URLs](#assembling-pazpar2-urls) section below.
979
980 sp_auth_query             _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2
981                                                       URLs](#assembling-pazpar2-urls) section below.
982
983 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
984                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
985                           record,                     section above.
986                           records,
987                           results
988
989 targetfilter              facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
990                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
991                           record,                     section above.
992                           records,
993                           results
994
995 targets                   facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
996                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
997                           record,                     section above.
998                           records,
999                           results
1000
1001 template                  details,  string            Numerous widgets use Handlebars templates to render HTML. In general, each
1002                           done,                       of these by default uses a template with the same name as the widget
1003                           facet,                      itself. Individual widgets can be customised to use a template of a
1004                           facets,                     different name by means of their `template` setting. The `records` widget
1005                           images,                     (and `record`, an equivalent that shows only a single record) use the
1006                           lang,                       `summary` template as well as the `records` template.
1007                           navi,
1008                           pager,
1009                           progress,
1010                           ranking,
1011                           records,
1012                           reference,
1013                           results,
1014                           search,
1015                           stat,
1016                           switch,
1017                           targets
1018
1019 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
1020
1021 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
1022                                                       than raw Pazpar2. An authentication phase is run during initialisation.
1023 ----
1024
1025 The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
1026 widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
1027 customise the display than by providing a full HTML structure.
1028
1029 ### Notes
1030
1031 1. The default for `facets` is `["xtargets", "subject", "author"]`
1032
1033 2. The default for `perpage_options` is `[10, 20, 30, 50]`
1034
1035 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
1036
1037 4. The default for `pp2_path` is `"service-proxy/"`
1038
1039 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
1040
1041 6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
1042
1043 ### Indirect settings
1044
1045 The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
1046 example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
1047 query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
1048
1049 The currently supported types are:
1050
1051 * `param` -- uses the value of the specified query parameter for the URL. For example
1052 `<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
1053 invoked from the URL `http://example.com/magic/example.html?term=sushi`
1054
1055 * `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
1056 `!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
1057 invoked from the URL `http://example.com/magic/lookup/dinosaur`
1058
1059 * `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
1060   search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
1061   extraction and reversing, the use the HTML:
1062
1063 <!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
1064
1065                 <script>var _reversedParam = extractAndReverse("term");</script>
1066                 <div class="mkws-results" autosearch="!var!_reversedParam">
1067
1068 ### Assembling Pazpar2 URLs
1069
1070 Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
1071 assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
1072 endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
1073
1074 In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
1075 is generally made to the same endpoint as the other requests. However, the hostname used for authentication may if necessary be
1076 overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
1077 `sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
1078
1079 So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
1080 (sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
1081 and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
1082 URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.
1083
1084 Language specification
1085 ----------------------
1086
1087 Support for another UI language can be added by providing an entry in
1088 the `mkws_config` object whose name is `language_` followed by the
1089 name of the language: for example, `language_French` to support
1090 French. Then value of this entry must be a key-value lookup table,
1091 mapping the English-language strings of the UI into their equivalents
1092 in the specified language. For example:
1093
1094         var mkws_config = {
1095           language_French: {
1096             "Authors": "Auteurs",
1097             "Subjects": "Sujets",
1098             // ... and others ...
1099           }
1100         }
1101
1102 The following strings occurring in the UI can be translated:
1103
1104 * `Search complete: found`
1105 * `records`
1106 * `Displaying`
1107 * `to`
1108 * `of`
1109 * `found`
1110 * `Prev`
1111 * `Next`
1112 * `Sort by`
1113 * `and show`
1114 * `per page`
1115 * `Search`
1116 * `Active clients`
1117 * `Retrieved records`
1118 * `Records`
1119 * `Targets`
1120 * `Target ID`
1121 * `Hits`
1122 * `Diags`
1123 * `Records`
1124 * `State`
1125
1126 In addition, facet names can be translated:
1127
1128 * `Authors`
1129 * `Sources`
1130 * `Subjects`
1131
1132 and whatever field captions are defined by `facet_caption_*` settings.
1133
1134 And sort-orders:
1135
1136 * `relevance`
1137 * `title`
1138 * `newest`
1139 * `oldest`
1140
1141 and whatever sort-orders are defined by the `sort_options` setting.
1142
1143 Finally, the names of fields in the full-record display can be
1144 translated. These include, but may not be limited to:
1145
1146 * `Title`
1147 * `Date`
1148 * `Author`
1149 * `Links`
1150 * `Subject`
1151 * `Locations`
1152
1153 jQuery UI popup invocation
1154 --------------------------
1155
1156 The MasterKey Widget Set can be invoked in a popup window on top of the page.
1157
1158 Note that when using the `popup` layout, facilities from the jQuery UI
1159 toolkit are used, so it's necessary to include both CSS and JavaScript
1160 from that toolkit. The relevant lines are:
1161
1162         <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
1163         <link rel="stylesheet" type="text/css"
1164               href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
1165
1166         <div class="mkws-search"></div>
1167         <div class="mkws-popup" popup_width="1024" popup_height="650" popup_autoOpen="0">
1168           <div class="mkws-switch"></div>
1169           <div class="mkws-lang"></div>
1170           <div class="mkws-results"></div>
1171           <div class="mkws-targets"></div>
1172           <div class="mkws-stat"></div>
1173         </div>
1174
1175 ----
1176 Element         Type    Default             Description
1177 --------        -----   -------             ------------
1178 popup_width     string  880                 Width of the popup window (if used), in
1179                                             pixels.
1180
1181 popup_height    string  760                 Height of the popup window (if used), in
1182                                             pixels.
1183
1184 popup_button    string  `input.mkwsButton`  A click on this selector will trigger the
1185                                             popup to open
1186
1187 popup_modal     string  0                   Modal confirmation mode. Valid values are 0 or 1
1188
1189 popup_autoOpen  string  1                   Open popup window on load. Valid values are 0 or 1
1190
1191 ----
1192
1193 You can have more than one mkws-popup widgets on a page. Please use a different
1194 popup_button value to address the right ones.
1195
1196 The structure of the HTML generated by the MKWS widgets
1197 -------------------------------------------------------
1198
1199 In order to override the default CSS styles provided by the MasterKey Widget
1200 Set, it's necessary to understand that structure of the HTML elements that are
1201 generated within the widgets. This knowledge make it possible, for example,
1202 to style each `<div>` with class `term` but only when it occurs inside an
1203 element with class `mkws-facets`, so as to avoid inadvertently styling other
1204 elements using the same class in the non-MKWS parts of the page.
1205
1206 The HTML structure is as follows. As in CSS, #ID indicates a unique identifier
1207 and .CLASS indicates an instance of a class.
1208
1209         #mkwsSwitch
1210           a*
1211
1212         #mkwsLang
1213           ( a | span )*
1214
1215         #mkwsSearch
1216           form
1217             input#mkwsQuery type=text
1218             input#mkwsButton type=submit
1219
1220         #mkwsBlanket
1221           (no contents -- used only for masking)
1222
1223         #mkwsResults
1224           table
1225             tbody
1226               tr
1227                 td
1228                   #mkwsTermlists
1229                     div.title
1230                     div.facet*
1231                       div.termtitle
1232                       ( a span br )*
1233                 td
1234                   div#mkwsRanking
1235                     form#mkwsSelect
1236                       select#mkwsSort
1237                       select#mkwsPerpage
1238                   #mkwsPager
1239                   #mkwsNavi
1240                   #mkwsRecords
1241                     div.record*
1242                       span (for sequence number)
1243                       a (for title)
1244                       span (for other information such as author)
1245                       div.details (sometimes)
1246                         table
1247                           tbody
1248                             tr*
1249                               th
1250                               td
1251         #mkwsTargets
1252           #mkwsBytarget
1253             table
1254               thead
1255                 tr*
1256                   td*
1257               tbody
1258                 tr*
1259                   td*
1260
1261         #mkwsStat
1262           span.head
1263           span.clients
1264           span.records
1265
1266
1267 Appendix: compatibility roadmap
1268 ===============================
1269
1270 FIXME: more to write here.
1271
1272
1273 Old and new-style class-names
1274 -----------------------------
1275
1276 **NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
1277 without hyphens and with second and subsequent words capitalised. So
1278 instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
1279 used to specify team names used an `mkwsTeam_` prefix (with an
1280 underscore). So instead of `mkws-team-foo`, it used to be
1281 `mkwsTeam_foo`.
1282
1283 The 1.x series of MKWS releases recognise these old-style class-names
1284 as well as the canonical ones, as a facility for backwards
1285 compatibility. However, **these old class-names are deprecated, and
1286 support will be removed in v2.0**. Existing applications that use them
1287 should be upgraded to the new-style class names as soon as convenient.
1288
1289
1290 - - -
1291
1292 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>