X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=tools%2Fhtdocs%2Fwhitepaper.markdown;h=376da7a51846b5f6d82112fad255e2b8db261ecf;hb=2681321da7a6c02655b92fc46832c5d80f90e6c1;hp=fdc663ba75b9a645a298ae5631558b3d13fa00e2;hpb=d11670bf9c703d51af48a6b1f968654ae3751311;p=mkws-moved-to-github.git diff --git a/tools/htdocs/whitepaper.markdown b/tools/htdocs/whitepaper.markdown index fdc663b..376da7a 100644 --- a/tools/htdocs/whitepaper.markdown +++ b/tools/htdocs/whitepaper.markdown @@ -19,13 +19,13 @@ Index Data provides several different toolkits for communicating with 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 @@ -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: @@ -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 @@ -249,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 @@ -269,66 +338,71 @@ 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_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with - datestamps, 3 = messages with datestamps and stack-traces. +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. + +facets array *Note 1* Ordered list of names of facets to display. Supported facet names are + `xtargets`, `subject` and `author`. -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 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_options array [] A list of the languages to offer as options. If empty (the default), then all + configured languages are listed. -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. 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* 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_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. +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_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. -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_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_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_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`. -show_lang bool true Indicates whether or not to display the language menu. +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_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. +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_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_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. +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 @@ -356,16 +430,16 @@ structure. ### 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 ... } } @@ -414,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 @@ -443,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