X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fwhitepaper.markdown;h=d71243d1263998742187f6846cb19d3322de38ee;hb=74036ea894f0b4b8258f38131d12b138c4b1f069;hp=76cb5e9d30930a3604dbffdf9e188259ba317ec9;hpb=f7aaf0b5a9d4589832611c14ea77ca40d01121ad;p=mkws-moved-to-github.git diff --git a/doc/whitepaper.markdown b/doc/whitepaper.markdown index 76cb5e9..d71243d 100644 --- a/doc/whitepaper.markdown +++ b/doc/whitepaper.markdown @@ -1,6 +1,5 @@ % Embedded metasearching with the MasterKey Widget Set % Mike Taylor -% July-September 2013 Introduction @@ -84,7 +83,7 @@ header, which are loaded from the tool site mkws.indexdata.com: contains all the JavaScript needed by the widget-set. * `mkws.css` - provides the default CSS styling + provides the default CSS styling Second, within the HTML body, `
` elements with special IDs that begin `mkws` can be provided. These are filled in by the MKWS code, @@ -260,8 +259,8 @@ If individual result-related components are in use in place of the all-in-one mkwsResults, then the redesigned application needs to specify the locations where the termlists should appear in both cases. In this case, wrap the wide-screen `mkwsTermlists` element in a -`mkwsTermlist-Container-wide` element; and provide an -`mkwsTermlist-Container-narrow` element in the place where the narrow-screen +`mkwsTermlists-Container-wide` element; and provide an +`mkwsTermlists-Container-narrow` element in the place where the narrow-screen termlists should appear. @@ -273,9 +272,14 @@ generally visible on the page is a search box, and the results appear in a popup. The key part of such an application is this invocation of the MKWS jQuery plugin: - +
+
+
+
+
+
+
+
The necessary scaffolding can be seen in an example application, http://example.indexdata.com/index-popup.html @@ -293,42 +297,8 @@ 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. +resources). For information on how to do this, see +[MKWS Target Selection](library-configuration.html) Reference Guide @@ -350,7 +320,7 @@ 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 +facets array *Note 1* Ordered list of names of facets to display. Supported facet names are `xtargets`, `subject` and `author`. lang string en Code of the default language to display the UI in. Supported language codes are `en` = @@ -394,6 +364,9 @@ show_perpage bool true Indicates whether or not to display show_sort bool true Indicates whether or not to display the sort menu. +show_switch bool true Indicates whether or not to display the switch menu, for switching between showing + retrieved records and target information. + sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort` array. @@ -405,8 +378,8 @@ use_service_proxy bool true If true, then a Service Proxy is use Pazpar2. --- -Perhaps we should get rid of the `show_lang`, `show_perpage` and -`show_sort` configuration items, and simply display the relevant menus +Perhaps we should get rid of the `show_lang`, `show_perpage`, +`show_sort` and `show_switch` 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 @@ -477,48 +450,43 @@ and -### jQuery plugin invocation +### jQuery UI popup invocation -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: +The MasterKey Widget Set can be invoked in a popup window on top of the page. - +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: -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: +
+
+
+
+
+
+
+
- +--- ### The structure of the HTML generated by the MKWS widgets @@ -592,4 +560,4 @@ and .CLASS indicates an instance of a class. - - - -Copyright (C) 2013 by IndexData ApS, +Copyright (C) 2013-2014 by IndexData ApS,