Last part of MKWS-58.
[mkws-moved-to-github.git] / doc / mkws-manual.markdown
1 % The MKWS manual: embedded metasearching with the MasterKey Widget Set
2 % Mike Taylor
3 % November 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 `waiting`         An image, defaulting to <http://mkws.indexdata.com/progress.gif> unless overridden with the `src` configuration
825                   item, which is initially invisible, appears when a search is submitted, and disappears when the search is
826                   complete.
827
828 ----
829
830
831 Configuration settings
832 ----------------------
833
834 Configuration settings may be provided at the level of a indiviual widget, or a team, or globally. Per-widget configuration is
835 described above; per-team settings can be placed in a `config` widget belonging to the relevant team, and will be applied to that
836 team as a whole; and global settings are provided in the global variable `mkws_config`. This structure is a key-value lookup
837 table, and may specify the values of many settings.
838
839 Some settings apply only to specific widgets; others to the behaviour of the tookit as a whole. When a widget does not itself have
840 a value specified for a particular configuration setting, its team is consulted; and if that also does not have a value, the global
841 settings are consulted. Only if this, too, is unspecified, is the default value used.
842
843 The supported configuration settings are described in the table below. For those settings that apply only to particular widgets,
844 the relevant widgets are listed. All entries are optional, but if specified must be given values of the specified type. Long
845 default values are in footnotes to keep the table reasonably narrow.
846
847 ----
848 Setting                   Widget    Type    Default   Description
849 --------                  ------    -----   --------- ------------
850 autosearch                facet,    string            If provided, this setting contains a query which is immediately run on behalf
851                           facets,                     of the team. Often used with an [indirect setting](#indirect-settings).
852                           record,
853                           records,
854                           results
855
856 facet                     facet     string            For a `facet` widget, this setting is mandatory, and indicates which field to
857                                                       list terms for. Three fields are supported: `subject`, `author` and
858                                                       `xtargets` -- the latter a special case which treats the target providing a
859                                                       record as a facet. Any other field may also be used, but the default caption
860                                                       and maximum term-count may not be appropriate, needing to be overridden by
861                                                       `facet_caption_*` and `facet_max_*` settings.
862
863 facet_caption_*           facet     string            Specifies what on-screen caption is to be used for the named facet: for
864                                                       example, if a `date` facet is generated, then `facet_caption_date` can be
865                                                       used to set the caption to "Year".
866
867 facet_max_*               facet     int               Specifies how many terms are to be displayed for the named facet: for
868                                                       example, if a `publisher` facet is generated, then `facet_max_publisher` can
869                                                       be used to limit the list to the top six.
870
871 facets                    _team_    array   *Note 1*  Ordered list of names of facets to display.
872
873 freeze_opacity            records   float             If defined, a fractional value between in the range 0.0 (transparent) to 1.0
874                                                       (opaque). During the short period after a mouse-move over the records when
875                                                       the display will not be updated, the widget is faded to that opacity
876                                                       (reverting to full opacity when the period elapses or the mouse leaves the
877                                                       area).
878
879 lang                      _team_    string            The code of the default language to display the UI in. Supported
880                                                       language codes are `en` = English, `de` = German, `da` = Danish, and whatever
881                                                       additional languages are configured using `language_*` entries (see below).
882
883 lang_options              lang      array   []        A list of the languages to offer as options. If empty (the default), then all
884                                                       configured languages are listed.
885
886 language_*                _global_  hash              Support for any number of languages can be added by providing entries whose
887                                                       name is `language_` followed by the code of the language. See the separate
888                                                       section below for details.
889
890 limit                     facet,    string            Allows a partial search to be included in the specification of an
891                           facets,                     auto-executing widget. This is ANDed with the submitted query, as though it
892                           record,                     had been selected from a facet. See the Search section in [the Protocol
893                           records,                    chapter of the Pazpar2 manual
894                           results                     ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
895
896 log_level                 _global_  string  info      The lowest level of logging output to emit. Acceptable values are
897                                                       `trace`, `debug`, `info`, `warn`, `error` and `fatal`.
898
899 maxrecs                   facet,    int               Limits the metasearching middleware to retrieving no more than the specified
900                           facets,                     number of records from each target.
901                           record,
902                           records,
903                           results
904
905 newsearch_opacity         records,  float             If defined, a fractional value between in the range 0.0 (transparent) to 1.0
906                           facets                      (opaque). When a new search is submitted, the widget fades to that opacity
907                                                       (reverting to full opacity when data arrives).
908
909 paragraphs                reference int               Limits the number of paragraphs rendered to the specified number. If
910                                                       omitted, there is no limit.
911
912 pazpar2_url               _global_  string            If specified, this is the URL used to access the metasearch middleware. This
913                                                       service must be configured to provide search results, facets, etc. It may be
914                                                       either unmediated Pazpar2 or the MasterKey Service Proxy, which mediates
915                                                       access to an underlying Pazpar2 instance. When not specified, the URL is
916                                                       assembled from `pp2_hostname` and `pp2_path`. See the [Assembling Pazpar2
917                                                       URLs](#assembling-pazpar2-urls) section below.
918
919 perpage                   facet,    int               Specifies the number of records to show per page in an auto-executing
920                           facets,                     widget. Contrast with `perpage_default`, which is used to prime the dropdown
921                           record,                     with which a user chooses the page-size in an interactive session.
922                           records,
923                           results
924
925 perpage_default           _team_    string  20        The initial value for the number of records to show on each page.
926
927 perpage_options           ranking   array   *Note 2*  A list of candidate page sizes. Users can choose between these to determine
928                                                       how many records are displayed on each page of results.
929
930 pp2_hostname              _global_  string  *Note 3*  Unless overridden by the `pazpar2_url` setting, this is used together with
931                                                       `pp2_path` to construct the URL to the Pazpar2 service (or Service
932                                                       Proxy). Set this to connect to a service on a different host from the
933                                                       default.
934
935 pp2_path                  _global_  string  *Note 4*  Unless overridden by the `pazpar2_url` setting, this is used together with
936                                                       `pp2_hostname` to construct the URL to the Pazpar2 service (or Service
937                                                       Proxy). Set this to connect to a service on a different host from the
938                                                       default.
939
940 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
941                                                       widgets. If set to true, a different approach is used which may be faster
942                                                       under some circumstances.
943
944 sentences                 reference int               Limits the number of sentences rendered to the specified number. If
945                                                       omitted, there is no limit.
946
947 service_proxy_auth        _global_  url               If defined, this is the URL which, when `use_service_proxy` is true, is
948                                                       fetched once at the beginning of each session to authenticate the user and
949                                                       establish a session that encompasses a defined set of targets to search
950                                                       in. When not defined, the URL is assembled from `sp_auth_hostname` or
951                                                       `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and
952                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
953                                                       URLs](#assembling-pazpar2-urls) section below.
954
955 service_proxy_auth_domain _global_  domain            When the server used for authentication -- e.g. the one identified by the
956                                                       `service_proxy_auth` URL -- proxies for different server, this can be set to
957                                                       the domain of the server that it proxies for, so that cookies are rewritten
958                                                       to appear to be from this domain.
959
960 show_lang                lang       bool    true      Indicates whether or not to display the language menu.
961
962 show_perpage             ranking    bool    true      Indicates whether or not to display the perpage menu.
963
964 show_sort                ranking    bool    true      Indicates whether or not to display the sort menu.
965
966 show_switch              switch     bool    true      Indicates whether or not to display the switch menu.
967
968 sort                      facet,    string            Specifies the order in which to sort the records retrieved by an
969                           facets,                     auto-executing widget. Must be one of those in the `sort_options`
970                           record,                     array. Contrast with `sort_default`, which is used to prime the dropdown
971                           records,                    with which a user chooses the sortorder in an interactive session.
972                           results
973
974 sort_default              _team_    string  relevance The default sort criterion to use. Must be one of those in the
975                                                       `sort_options` array.
976
977 sort_options              ranking   array   *Note 5*  List of supported sort criteria. Each element of the list is itself a
978                                                       two-element list: the first element of each sublist is a pazpar2
979                                                       sort-expression such as `data:0` and the second is a human-readable label
980                                                       such as `newest`.
981
982 sp_auth_credentials       _global_  string            If defined, this must be a slash-separated combination of username and
983                                                       password, which is sent as the authentication credentials on session
984                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
985                                                       section below.
986
987 sp_auth_hostname          _global_  string            If provided, overrides the `pp2_hostname` setting when constructing the
988                                                       Service Proxy authentication URL. This need only be used when authentication
989                                                       is performed on a different host from the remaining operations (search,
990                                                       retrieve, etc.)
991
992 sp_auth_path              _global_  string            Part of the URL used for authentication. See the [Assembling Pazpar2
993                                                       URLs](#assembling-pazpar2-urls) section below.
994
995 sp_auth_query             _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2
996                                                       URLs](#assembling-pazpar2-urls) section below.
997
998 src                       waiting   url               The address of an image to use in the `waiting` widget in place of the
999                                                       default spinning wheel. Used to indicate that a search is in progress.
1000
1001 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
1002                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
1003                           record,                     section above.
1004                           records,
1005                           results
1006
1007 targetfilter              facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
1008                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
1009                           record,                     section above.
1010                           records,
1011                           results
1012
1013 targets                   facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
1014                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
1015                           record,                     section above.
1016                           records,
1017                           results
1018
1019 template                  details,  string            Numerous widgets use Handlebars templates to render HTML. In general, each
1020                           done,                       of these by default uses a template with the same name as the widget
1021                           facet,                      itself. Individual widgets can be customised to use a template of a
1022                           facets,                     different name by means of their `template` setting. The `records` widget
1023                           images,                     (and `record`, an equivalent that shows only a single record) use the
1024                           lang,                       `summary` template as well as the `records` template.
1025                           navi,
1026                           pager,
1027                           progress,
1028                           ranking,
1029                           records,
1030                           reference,
1031                           results,
1032                           search,
1033                           stat,
1034                           switch,
1035                           targets
1036
1037 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
1038
1039 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
1040                                                       than raw Pazpar2. An authentication phase is run during initialisation.
1041 ----
1042
1043 The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
1044 widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
1045 customise the display than by providing a full HTML structure.
1046
1047 ### Notes
1048
1049 1. The default for `facets` is `["xtargets", "subject", "author"]`
1050
1051 2. The default for `perpage_options` is `[10, 20, 30, 50]`
1052
1053 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
1054
1055 4. The default for `pp2_path` is `"service-proxy/"`
1056
1057 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
1058
1059 6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
1060
1061 ### Indirect settings
1062
1063 The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
1064 example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
1065 query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
1066
1067 The currently supported types are:
1068
1069 * `param` -- uses the value of the specified query parameter for the URL. For example
1070 `<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
1071 invoked from the URL `http://example.com/magic/example.html?term=sushi`
1072
1073 * `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
1074 `!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
1075 invoked from the URL `http://example.com/magic/lookup/dinosaur`
1076
1077 * `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
1078   search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
1079   extraction and reversing, the use the HTML:
1080
1081 <!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
1082
1083                 <script>var _reversedParam = extractAndReverse("term");</script>
1084                 <div class="mkws-results" autosearch="!var!_reversedParam">
1085
1086 ### Assembling Pazpar2 URLs
1087
1088 Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
1089 assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
1090 endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
1091
1092 In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
1093 is generally made to the same endpoint as the other requests. However, the hostname used for authentication may if necessary be
1094 overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
1095 `sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
1096
1097 So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
1098 (sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
1099 and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
1100 URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.
1101
1102 Language specification
1103 ----------------------
1104
1105 Support for another UI language can be added by providing an entry in
1106 the `mkws_config` object whose name is `language_` followed by the
1107 name of the language: for example, `language_French` to support
1108 French. Then value of this entry must be a key-value lookup table,
1109 mapping the English-language strings of the UI into their equivalents
1110 in the specified language. For example:
1111
1112         var mkws_config = {
1113           language_French: {
1114             "Authors": "Auteurs",
1115             "Subjects": "Sujets",
1116             // ... and others ...
1117           }
1118         }
1119
1120 The following strings occurring in the UI can be translated:
1121
1122 * `Search complete: found`
1123 * `records`
1124 * `Displaying`
1125 * `to`
1126 * `of`
1127 * `found`
1128 * `Prev`
1129 * `Next`
1130 * `Sort by`
1131 * `and show`
1132 * `per page`
1133 * `Search`
1134 * `Active clients`
1135 * `Retrieved records`
1136 * `Records`
1137 * `Targets`
1138 * `Target ID`
1139 * `Hits`
1140 * `Diags`
1141 * `Records`
1142 * `State`
1143
1144 In addition, facet names can be translated:
1145
1146 * `Authors`
1147 * `Sources`
1148 * `Subjects`
1149
1150 and whatever field captions are defined by `facet_caption_*` settings.
1151
1152 And sort-orders:
1153
1154 * `relevance`
1155 * `title`
1156 * `newest`
1157 * `oldest`
1158
1159 and whatever sort-orders are defined by the `sort_options` setting.
1160
1161 Finally, the names of fields in the full-record display can be
1162 translated. These include, but may not be limited to:
1163
1164 * `Title`
1165 * `Date`
1166 * `Author`
1167 * `Links`
1168 * `Subject`
1169 * `Locations`
1170
1171 jQuery UI popup invocation
1172 --------------------------
1173
1174 The MasterKey Widget Set can be invoked in a popup window on top of the page.
1175
1176 Note that the `popup` widget uses facilities from the jQuery UI, so
1177 it's necessary to include both CSS and JavaScript from that
1178 toolkit. The relevant lines are:
1179
1180         <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
1181         <link rel="stylesheet" type="text/css"
1182               href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
1183
1184         <div class="mkws-search"></div>
1185         <div class="mkws-popup" popup_width="1024" popup_height="650" popup_autoOpen="0">
1186           <div class="mkws-switch"></div>
1187           <div class="mkws-lang"></div>
1188           <div class="mkws-results"></div>
1189           <div class="mkws-targets"></div>
1190           <div class="mkws-stat"></div>
1191         </div>
1192
1193 Popup windows can contain any HTML, not just MKWS widgets.
1194
1195 The properties of the `popup` widget are as follows:
1196
1197 ----
1198 Setting         Type    Default             Description
1199 --------        -----   -------             ------------
1200 popup_width     int     880                 Width of the popup window, in pixels.
1201
1202 popup_height    int     760                 Height of the popup window, in pixels.
1203
1204 popup_button    string  `input.mkwsButton`  A jQuery selector identifying the element which, which clicked, pops up the window.
1205
1206 popup_modal     bool    0                   Indicates whether the popup is modal (blocks access to the background page until
1207                                             dismissed). Set to 1 if a modal popup is required.
1208
1209 popup_autoOpen  bool    1                   Indictaes whether to pop up the window automatically when the page is loaded.
1210
1211 ----
1212
1213 Multiple `popup` widgets can co-exist on a page. In this case, different
1214 `popup_button` values must be used for each.
1215
1216 Structure of HTML generated by widgets
1217 --------------------------------------
1218
1219 In order to override the default CSS styles provided by the MasterKey Widget
1220 Set, it's necessary to understand the structure of the HTML elements that are
1221 generated within the widgets. The HTML structure is as follows. As in CSS,
1222 _.class_ indicates an instance of a class. A trailing `*` indicates zero or
1223 more instances; a trailing `?` indicates zero or one instance.
1224
1225         .mkws-progress
1226           span.mkws-done
1227           span.mkws-waiting
1228         
1229         .mkws-search
1230           form.mkws-search-form
1231             input.mkws-query
1232             input.mkws-button
1233         
1234         .mkws-results
1235           table
1236             tbody
1237               tr
1238                 td.mkws-facets-container-wide
1239                   div.mkws-facets
1240                     div.mkws-facet*
1241                       div.mkws-facet-title
1242                       div.mkws-term*
1243                         a
1244                         span
1245                 td.mkws-motd-container
1246                   div.mkws-ranking
1247                     form
1248                       select.mkws-sort
1249                         option*
1250                       select.mkws-perpage
1251                         option*
1252                   div.mkws-pager
1253                     div
1254                     div
1255                       span.mkws-prev
1256                       span.mkws-current-page
1257                       a*
1258                       span.mkws-next
1259                   div.mkws-navi
1260                   div.mkws-records
1261                     div.mkws-summary*
1262                       div.mkws-field-data
1263                         span.mkws-field-NAME*
1264                       div.mkws-details?
1265                         table
1266                           tbody
1267                             tr*
1268                               th
1269                               td
1270               tr
1271                 td
1272                   div.mkws-facets-container-narrow
1273         
1274         .mkws-targets
1275           table
1276             thead
1277               tr
1278                 td*
1279             tbody
1280               tr*
1281                 td*
1282         
1283
1284 Appendix: compatibility roadmap
1285 ===============================
1286
1287 Wherever possible, we ensure that all functional changes in MKWS are
1288 backwards-compatible, so that applications written against old versions of the
1289 toolkit will continue to work when running against newer versions.
1290
1291 However, a few aspects of functionality unavoidably change in backwards
1292 incompatible ways. We ensure that **this only happens with new major
1293 versions** -- so it should _always_ be safe to upgrade to a new minor version.
1294 As an aid to porting old applications, we here note the specific
1295 backwards-incompatible changes in the various major releases, and those
1296 planned for future major releases.
1297
1298
1299 Major version 1.x
1300 -----------------
1301
1302 Versions of MKWS before v1.0 (including the only prior release, v0.9.1) used
1303 camel-case class-names: without hyphens and with second and subsequent words
1304 capitalised. So instead of `mkws-search`, it used to be `mkwsSearch`. And the
1305 classes used to specify team names used an `mkwsTeam_` prefix (with an
1306 underscore). So instead of `mkws-team-foo`, it used to be `mkwsTeam_foo`.
1307
1308 The 1.x series of MKWS releases recognise these old-style class-names
1309 as well as the canonical ones, as a facility for backwards
1310 compatibility. However, **these old class-names are deprecated, and
1311 support will be removed in v2.0**. Existing applications that use them
1312 should be upgraded to the new-style class names as soon as convenient.
1313
1314
1315 - - -
1316
1317 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>