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>