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. @@ -200,9 +200,43 @@ Refinements 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. +`mkwsMOTD` division anywhere on the page. It will be moved into the +`mkwsResults` area and initially displayed, 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 classes that begin with +the string `mkwsTemplate_`. At present, the supported templates are: + +* `mkwsTemplate_Summary` -- used for each summary record in a list of + results. + +* `mkwsTemplate_Record` -- 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 `mkwsTemplate_Summary` +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: + + + +For details of Handlebars template syntax, see +[the online documentation](http://handlebarsjs.com/). ### Responsive design @@ -213,13 +247,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: @@ -251,17 +283,52 @@ 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. +By default, MKWS configures itself to use a demonstration account on a +service hosted by mkws.indexdata.com. This account (username `demo`, +password `demo`) provides access to about a dozen free data +sources. Authentication onto this service is via an authentication URL +on the same MKWS server, so no explicit configuration is needed. + +In order to search in a customised set of targets, including +subscription resources, it's necessary to create an account with +Index Data's hosted service proxy, and protect that account with +authentication tokens (to prevent unauthorised use of subscription +resources). But in order to gain access to those resources, the +authentication tokens have to be available to the widgets in some way, +and simple embedding them in the JavaScript configuration is not +acceptable because they are easy to read from there. + +The solution to this problem is in three steps. + +First +the application's web-server creates a rewriting rule that takes an +innocuous URL like +http://example.indexdata.com/service-proxy-auth/ +and rewrites it as an access to Index Data's authentication service +with authentication credentials embedded. This can be done using +Apache2 directives such as + + RewriteEngine on + RewriteRule /service-proxy-auth/ + http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=U&password=PW [P] + +Because the credentials appear only in the application's web-server +configuration, they are not visible to malicious users. + +Second, the broader application that includes MKWS widgets must +protect access to the authentication URL on its own web-server. This +can be done using IP authentication, a local username/password scheme, +Kerberos or any other means. + +Third, the MKWS application must be configured to use the +application-hosted authentication URL instead of the default one. This +is done by means of the `service_proxy_auth` configuration element, +which should be set to the authentication URL. + +Once these three steps are taken, the MKWS application will +authenticate by means of a special URL on the application's web +server, which the application prevents unauthorised access to, and the +underlying credentials are hidden. Reference Guide @@ -271,80 +338,80 @@ 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; -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 optional, 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 - 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`. +Element Type Default Description +-------- ----- --------- ------------ +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. -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). +facets array *Note 1* Ordered list of names of facets to display. Supported facet names are + `xtargets`, `subject` and `author`. -lang_display array [] A list of the languages to offer as options. If empty (the default), then all - configured languages are listed. +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_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. +lang_options array [] A list of the languages to offer as options. If empty (the default), then all + configured languages are listed. -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 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 - 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. -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_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_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. +query_width int 50 The width of the query box, in characters. -query_width int 50 The width of the query box, in characters. +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. -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. +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_width int 980 If `responsive_design` is true, this is the threshhold width, in pixels, at which the - facets move between their two locations. +service_proxy_auth_domain domain Can be set to the domain for which `service_proxy_auth` proxies authentication, so + that cookies are rewritten to appear to be from this domain. In general, this is not + necessary, as this setting defaults to the domain of `pazpar2_url`. -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. +show_lang bool true Indicates whether or not to display the language menu. -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. +show_perpage bool true Indicates whether or not to display the perpage menu. -sort 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_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. +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. +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. +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"] @@ -363,16 +430,16 @@ use_service_proxy bool true If true, then a Service Proxy is used ### 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 ... } } @@ -421,9 +488,9 @@ 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 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 @@ -450,7 +517,8 @@ 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