its metasearching middleware, trading off varying degrees of
flexibility against convenience:
-* libpz2.js -- a low-level JavaScript library for interrogating the
+* pz2.js -- a low-level JavaScript library for interrogating the
Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer
to create JavaScript applications display facets, records, etc. that
are fetched from the metasearching middleware.
* masterkey-ui-core -- a higher-level, complex JavaScript library that
- uses libpz2.js to provide the pieces needed for building a
+ uses pz2.js to provide the pieces needed for building a
full-featured JavaScript application.
* MasterKey Demo UI -- an example of a searching application built on
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>MKWS demo client</title>
<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
- <link rel="stylesheet" href="http://mkws.indexdata.com/mkwsStyle.css" />
+ <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
</head>
<body>
<div id="mkwsSearch"></div>
* `mkws-complete.js`
contains all the JavaScript needed by the widget-set.
-* `mkwsStyle.css`
+* `mkws.css`
provides the default CSS styling
Second, within the HTML body, `<div>` elements with special IDs that
-------------
Many aspects of the behaviour of MKWS can be modified by setting
-parameters into the `mkws_config` hash. **This must be done *before*
+parameters into the `mkws_config` object. **This must be done *before*
including the MKWS JavaScript** so that when that code is executed it
can refer to the configuration values. So the HTML header looks like
this:
var mkws_config = {
lang: "da",
sort_default: "title",
- query_width: 60,
+ query_width: 60
};
</script>
<script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
Customisation of MKWS searching widgets can also be achieved by
overriding the styles set in the toolkit's CSS stylesheet. The default
-styles can be inspected in `mkwsStyle.css` and overridden in any
+styles can be inspected in `mkws.css` and overridden in any
styles that appears later in the HTML than that file. At the simplest
level, this might just mean changing fonts, sizes and colours, but
more fundamental changes are also possible.
but will be hidden when a search is made.
+### Customised display using Handlebars templates
+
+Certain aspects of the widget-set's display can be customised by
+providing Handlebars templates with well-known IDs that begin with the
+string `mkwsTemplate`. At present, the supported templates are:
+
+* `mkwsTemplateSummary` -- used for each summary record in a list of
+ results.
+
+* `mkwsTemplateRecord` -- used when displaying a full record.
+
+For both of these the metadata record is passed in, and its fields can
+be referenced in the template. As well as the metadata fields
+(`md-*`), two special fields are provided to the `mkwsTemplateSummary`
+template, for creating popup links for full records. These are `_id`,
+which must be provided as the `id` attribute of a link tag, and
+`_onclick`, which must be provided as the `onclick` attribute.
+
+For example, an application can install a simple author+title summary
+record in place of the usual one providing the following template:
+
+ <script id="mkwsTemplateSummary" type="text/x-handlebars-template">
+ {{#if md-author}}
+ <span>{{md-author}}</span>
+ {{/if}}
+ <a href="#" id="{{_id}}" onclick="{{_onclick}}">
+ <b>{{md-title}}</b>
+ </a>
+ </script>
+
+For details of Handlebars template syntax, see
+[the online documentation](http://handlebarsjs.com/).
+
+
### Responsive design
Metasearching applications may need to appear differently on
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;
-long default values are in footnotes to keep the table reasonably narrow.
+is a key-value lookup table, 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; long default values are in footnotes to keep the table
+reasonably narrow.
---
Element Type Default Description
-------- ----- --------- ------------
-debug int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
+debug_level 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
lang_options array [] A list of the languages to offer as options. If empty (the default), then all
configured languages are listed.
-show_lang bool true Indicates whether or not to display the language menu.
-
language_* hash Support for any number of languages can be added by providing entries whose name is
`language_` followed by the code of the language. See the separate section below for
details.
MasterKey Service Proxy, which mediates access to an underlying Pazpar2 instance. In
the latter case, `service_proxy_auth` must be provided.
-perpage_options array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many
- records are displayed on each page of results.
-
perpage_default string 20 The initial value for the number of records to show on each page.
-show_perpage bool true Indicates whether or not to display the perpage menu.
+perpage_options array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many
+ records are displayed on each page of results.
query_width int 50 The width of the query box, in characters.
session to authenticate the user and establish a session that encompasses a defined set
of targets to search in.
-sort_options array *Note 6* List of supported sort criteria. Each element of the list is itself a two-element list:
- the first element of each sublist is a pazpar2 sort-expression such as `data:0` and
- the second is a human-readable label such as `newest`.
+show_lang bool true Indicates whether or not to display the language menu.
+
+show_perpage bool true Indicates whether or not to display the perpage menu.
+
+show_sort bool true Indicates whether or not to display the sort menu.
sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort`
array.
-show_sort bool true Indicates whether or not to display the sort menu.
+sort_options array *Note 6* List of supported sort criteria. Each element of the list is itself a two-element list:
+ the first element of each sublist is a pazpar2 sort-expression such as `data:0` and
+ the second is a human-readable label such as `newest`.
use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw
- Pazpar2. ### Do we even need this? Can't we just assume that the Service Proxy is in
- use when and only when `service_proxy_auth` is defined? Alternatively, retain this, but
- use the same entry to specify the URL in either case.
+ Pazpar2.
---
Perhaps we should get rid of the `show_lang`, `show_perpage` and
### Language specification
Support for another UI language can be added by providing an entry in
-the `mkws_config` hash whose name is `language_` followed by the name
-of the language: for example, `language_Arabic` to support
-Arabic. Then value of this entry must be a hash, mapping the
-English-language strings of the UI into their equivalents in the
-specified language. For example:
+the `mkws_config` object whose name is `language_` followed by the
+name of the language: for example, `language_French` to support
+French. Then value of this entry must be a key-value lookup table,
+mapping the English-language strings of the UI into their equivalents
+in the specified language. For example:
var mkws_config = {
- language_Arabic: {
- "Authors": "الكتاب",
- "Subjects": "المواضيع",
+ language_French: {
+ "Authors": "Auteurs",
+ "Subjects": "Sujets",
// ... and others ...
}
}
This code should be inserted in the page at the position where the
metasearch should occur.
-When invoking this plugin, a hash of named options may be passed in to
-modify the default behaviour, as in the exaple above. The available
-options are as follows:
+When invoking this plugin, a key-value lookup table of named options
+may be passed in to modify the default behaviour, as in the exaple
+above. The available options are as follows:
---
Element Type Default Description
projects / mkws-moved-to-github.git / blobdiff