MKWS demo client

` elements with special IDs that @@ -128,7 +128,7 @@ Configuration ------------- 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: @@ -137,7 +137,7 @@ this: var mkws_config = { lang: "da", sort_default: "title", - query_width: 60, + query_width: 60 }; @@ -180,7 +180,7 @@ following lower-level components provided instead: 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. @@ -213,13 +213,11 @@ 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. -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: @@ -271,14 +269,16 @@ Reference Guide 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. +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 @@ -288,60 +288,233 @@ lang string en Code of the default language to displ English, `de` = German, `da` = Danish, and whatever additional languages are configured using `language_*` entries (see below). -lang_display array +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 +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. -language_* hash +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. -pazpar2_url string *Note 2* +perpage_default string 20 The initial value for the number of records to show on each page. -perpage array *Note 3* +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 +query_width int 50 The width of the query box, in characters. -perpage_menu bool true +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. -query_width int +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. -responsive_design bool +show_lang bool true Indicates whether or not to display the language menu. -responsive_design_width int 980 +show_perpage bool true Indicates whether or not to display the perpage menu. -service_proxy_auth url +show_sort bool true Indicates whether or not to display the sort menu. -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_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort` + array. -sort array *Note 5* +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 - -sort_menu bool true - -use_service_proxy bool true +use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw + 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"] +1. ["sources", "subjects", "authors"] + +2. /pazpar2/search.pz2 + +3. [10, 20, 30, 50] + +4. http://mkws.indexdata.com/service-proxy-auth -2: /pazpar2/search.pz2 +5. http://mkws.indexdata.com/service-proxy/ -3: ### +6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]] -4: http://mkws.indexdata.com/service-proxy/ -5: ### +### Language specification + +Support for another UI language can be added by providing an entry in +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_French: { + "Authors": "Auteurs", + "Subjects": "Sujets", + // ... 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: + + + +This code should be inserted in the page at the position where the +metasearch should occur. + +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 +-------- ----- --------- ------------ +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: + + + + ### 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 `

` 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 - - -