doc/mkws-manual.markdown

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