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