% Embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% 26 July 2013
+% July-September 2013
Introduction
reference guide below.
-Message of the day
-------------------
+Refinements
+-----------
- </td>\
- <td id="mkwsMOTDContainer" valign="top">\
+### Message of the day
-Responsive design
------------------
+Some applications might like to open with content in the area that
+will subsequently be filled with result-records -- a message of the
+day, a welcome message or a help page. This can be done by placing an
+`mkwsMOTDContainer` division on the page next to `mkwsResults` or
+`mkwsRecords`. The contents of this element are initially displayed,
+but will be hidden when a search is made.
- responsive_design: true
- responsive_design_width: 500
- <div id="mkwsTermlistContainer1">
- <div id="mkwsTermlistContainer2">
+### Responsive design
-Popup results with jQuery UI
-----------------------------
+Metasearching applications may need to appear differently on
+small-screened mobile devices, or change their appearance when
+screen-width changes (as when a small device is rotated). To achieve
+this, MKWS supports responsive design which will move the termlists to
+the bottom on narrow screens and to the sidebar on wide screens.
-TODO
+To turn on this behaviour, set the `responsive_design` configuration
+element to `true`, and `responsive_design_width` to the desired
+threshhold width in pixels. For example:
+
+ <script type="text/javascript">
+ var mkws_config = {
+ responsive_design: true,
+ responsive_design_width: 990
+ };
+ </script>
+If individual result-related components are in use in place of the
+all-in-one mkwsResults, then the redesigned application needs to
+specify the locations where the termlists should appear in both
+cases. In this case, wrap the wide-screen `mkwsTermlists` element in a
+`mkwsTermlistContainer1` element; and provide an
+`mkwsTermlistContainer2` element in the place where the narrow-screen
+termlists should appear.
-Authentication and target configuration
----------------------------------------
-TODO
+### Popup results with jQuery UI
+
+The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI)
+can be used to construct MKWS applications in which the only component
+generally visible on the page is a search box, and the results appear
+in a popup. The key part of such an application is this invocation of
+the MKWS jQuery plugin:
+
+ <script type="text/javascript">
+ jQuery.pazpar2({ "layout":"popup", width:800, height:500 });
+ </script>
+
+The necessary scaffolding can be seen in an example application,
+http://example.indexdata.com/index-popup.html
+
+
+### Authentication and target configuration
+
+By default, MKWS configures itself to use a demo account on a service
+hosted by mkws.indexdata.com. This demo account provides access to
+about a dozen free data sources. Authentication onto this service is
+via an authentication URL on the same server, which MKWS uses by
+default so no configuration is needed.
+
+Access to a customised set of resources (including resources that
+require authentication) can be provided. In this case, a
+customer-specific authentication URL is used to gain access to these
+rather than the default set. Contact Index Data on info@indexdata.com
+for details.
Reference Guide
### Configuration object
-TODO
+The configuration object `mkws_config` may be created before including
+the MKWS JavaScript code to modify default behaviour. This structure
+is a hash, whose entries are described in the table below. All entries
+are options, but if specified must be given values of the specified
+type. If ommitted, each setting takes the indicated default value.
+
+---
+Element Type Default Description
+-------- ----- --------- ------------
+debug int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
+ datestamps, 3 = messages with datestamps and stack-traces.
+
+facets array *Note 1* Ordered list of names of facets to display. Supported facet names are
+ `sources`, `subjects` and `authors`.
+
+lang string en Code of the default language to display the UI in. Supported language codes are `en` =
+ English, `de` = German, `da` = Danish, and whatever additional languages are configured
+ using `language_*` entries (see below).
+
+lang_display array
+
+lang_menu bool
+
+language_* hash
+
+pazpar2_url string *Note 2*
+
+perpage array *Note 3*
+
+perpage_default string
+
+perpage_menu bool true
+
+query_width int
+
+responsive_design bool
+
+responsive_design_width int 980
+
+service_proxy_auth url
+
+service_proxy_url string *Note 4* The URL on which the service proxy is accessed. This service must be configured to
+ provide search results, facets, etc.
+
+sort array *Note 5*
+
+sort_default string
+
+sort_menu bool true
+
+use_service_proxy bool true
+---
+
+#### Notes
+
+1: ["sources", "subjects", "authors"]
+
+2: /pazpar2/search.pz2
+
+3: ###
+
+4: http://mkws.indexdata.com/service-proxy/
+
+5: ###
+
### jQuery plugin invocation