this, MKWS supports responsive design which will move the termlists to
the bottom on narrow screens and to the sidebar on wide screens.
-To turn on this behaviour, set the `responsive_design` configuration
-element to `true`, and `responsive_design_width` to the desired
+To turn on this behaviour, set the `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>
English, `de` = German, `da` = Danish, and whatever additional languages are configured
using `language_*` entries (see below).
-lang_display array [] A list of the languages to offer as options. If empty (the default), then all
+lang_options array [] A list of the languages to offer as options. If empty (the default), then all
configured languages are listed.
-lang_menu bool true Indicates whether or not to display the language menu. ### We should get rid of this
- setting, and simply display the menu if there's an `mkwsLang` element.
+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.
-pazpar2_url string *Note 2* The URL used to access the metasearch middleware if `use_service_proxy` is false. ###
- It's silly that you have to provide a different setting depending on whether
- `use_service_proxy` is set. Should just use pazpar2_url in all cases.
+pazpar2_url string *Note 2* The URL used to access the metasearch middleware. This service must be configured to
+ provide search results, facets, etc. It may be either unmediated or Pazpar2 the
+ MasterKey Service Proxy, which mediates access to an underlying Pazpar2 instance. In
+ the latter case, `service_proxy_auth` must be provided.
-perpage array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many
+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. ### The `perpage` and
- `perpage_default` entries should be renamed `perpage_display` and `perpage`
- respectively for consistency with the language-related settings.
+perpage_default string 20 The initial value for the number of records to show on each page.
-perpage_menu bool true Indicates whether or not to display the perpage menu. ### We should get rid of this
- setting, and simply display the menu if an appropriate container is provided.
+show_perpage bool true Indicates whether or not to display the perpage menu.
query_width int 50 The width of the query box, in characters.
-responsive_design bool false If true, then the facets display moves between two locations as the screen-width
- varies, as described above. ### This entry should not exist: the design should be
- responsive whenever `responsive_design_width` has a defined value.
-
-responsive_design_width int 980 If `responsive_design` is true, this is the threshhold width, in pixels, at which the
- facets move between their two locations.
+responsive_design_width int If defined, then the facets display moves between two locations as the screen-width
+ varies, as described above. The specified number is the threshhold width, in pixels,
+ at which the facets move between their two locations.
service_proxy_auth url *Note 4* A URL which, when `use_service_proxy` is true, is fetched once at the beginning of each
session to authenticate the user and establish a session that encompasses a defined set
of targets to search in.
-service_proxy_url string *Note 5* The URL on which the service proxy is accessed if `use_service_proxy` is true. This
- service must be configured to provide search results, facets, etc.
-
-sort array *Note 6* List of supported sort criteria. Each element of the list is itself a two-element list:
+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`.
sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort`
array.
-sort_menu bool true Indicates whether or not to display the sort menu. ### We should get rid of this
- setting, and simply display the menu if an appropriate container is provided.
+show_sort bool true Indicates whether or not to display the sort menu.
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
+`show_sort` configuration items, and simply display the relevant menus
+only when their containers are provided -- e.g. an `mkwsLang` element
+for the language menu. But for now we retain these, as an easier route
+to lightly customise the display than my changing providing a full HTML
+structure.
+
#### Notes
1. ["sources", "subjects", "authors"]
### Language specification
-TODO
+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:
+
+ var mkws_config = {
+ language_Arabic: {
+ "Authors": "الكتاب",
+ "Subjects": "المواضيع",
+ // ... and others ...
+ }
+ }
+
+The following strings occurring in the UI can be translated:
+`Displaying`,
+`Next`,
+`Prev`,
+`Records`,
+`Search`,
+`Sort by`,
+`Targets`,
+`Termlists`,
+`and show`,
+`found`,
+`of`,
+`per page`
+and
+`to`.
+
+In addition, facet names can be translated:
+`Authors`,
+`Sources`
+and
+`Subjects`.
+
+Finally, the names of fields in the full-record display can be
+translated. These include, but may not be limited to:
+`Author`,
+`Date`,
+`Location`,
+`Subject`
+and
+`Title`.
+
+
### jQuery plugin invocation
-TODO
+The MasterKey Widget Set can be invoked as a jQuery plugin rather than
+by providing an HTML skeleton explicitly. When this approach is used,
+the invocation is a single line of JavaScript:
+
+ <script>jQuery.pazpar2();</script>
+
+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:
+
+---
+Element Type Default Description
+-------- ----- --------- ------------
+layout string popup Specifies how the user interface should
+ appear. Options are `table` (the default,
+ with facets at the bottom), `div` (with
+ facets at the side) and `popup` (to
+ obtain a popup window).
+
+width int 880 Width of the popup window (if used), in
+ pixels.
+
+height int 760 Height of the popup window (if used), in
+ pixels.
+
+id_button string input#mkwsButton (Never change this.)
+
+id_popup string #mkwsPopup (Never change this.)
+---
+
+Note that when using the `popup` layout, facilities from the jQuery UI
+toolkit are used, so it's necessary to include both CSS and JavaScript
+from that toolkit. The relevant lines are:
+
+ <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
+ <link rel="stylesheet" type="text/css" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
+
### The structure of the HTML generated by the MKWS widgets
-TODO
+In order to override the default CSS styles provided by the MasterKey Widget
+Set, it's necessary to understand that structure of the HTML elements that are
+generated within the components. This knowledge make it possible, for example,
+to style each `<div>` with class `term` but only when it occurs inside an
+element with ID `#mkwsTermlists`, so as to avoid inadvertently styling other
+elements using the same class in the non-MKWS parts of the page.
+
+The HTML structure is as follows. As in CSS, #ID indicates a unique identifier
+and .CLASS indicates an instance of a class.
+
+ #mkwsSwitch
+ a*
+
+ #mkwsLang
+ ( a | span )*
+
+ #mkwsSearch
+ form
+ input#mkwsQuery type=text
+ input#mkwsButton type=submit
+
+ #mkwsBlanket
+ (no contents -- used only for masking)
+
+ #mkwsResults
+ table
+ tbody
+ tr
+ td
+ #mkwsTermlists
+ div.title
+ div.facet*
+ div.termtitle
+ ( a span br )*
+ td
+ div#mkwsRanking
+ form#mkwsSelect
+ select#mkwsSort
+ select#mkwsPerpage
+ #mkwsPager
+ #mkwsNavi
+ #mkwsRecords
+ div.record*
+ span (for sequence number)
+ a (for title)
+ span (for other information such as author)
+ div.details (sometimes)
+ table
+ tbody
+ tr*
+ th
+ td
+ #mkwsTargets
+ #mkwsBytarget
+ table
+ thead
+ tr*
+ td*
+ tbody
+ tr*
+ td*
+
+ #mkwsStat
+ span.head
+ span.clients
+ span.records
- - -