% Embedded metasearching with the MasterKey Widget Set
% Mike Taylor
-% July-September 2013
Introduction
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, `<div>` elements with special IDs that
begin `mkws` can be provided. These are filled in by the MKWS code,
in a popup. The key part of such an application is this invocation of
the MKWS jQuery plugin:
- <script type="text/javascript">
- jQuery.pazpar2({ "layout":"popup", width:800, height:500 });
- </script>
+ <div class="mkwsSearch"></div>
+ <div class="mkwsPopup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
+ <div class="mkwsSwitch"></div>
+ <div class="mkwsLang"></div>
+ <div class="mkwsResults"></div>
+ <div class="mkwsTargets"></div>
+ <div class="mkwsStat"></div>
+ </div>
The necessary scaffolding can be seen in an example application,
http://example.indexdata.com/index-popup.html
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.
-
-<b>First</b>
-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.
-
-<b>Second</b>, 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.
-
-<b>Third</b>, 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
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` =
-### 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.
- <script>jQuery.pazpar2();</script>
+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.
+ <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" />
-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:
+ <div class="mkwsSearch"></div>
+ <div class="mkwsPopup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
+ <div class="mkwsSwitch"></div>
+ <div class="mkwsLang"></div>
+ <div class="mkwsResults"></div>
+ <div class="mkwsTargets"></div>
+ <div class="mkwsStat"></div>
+ </div
---
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
+popup_width string 880 Width of the popup window (if used), in
pixels.
-height int 760 Height of the popup window (if used), in
+popup_height string 760 Height of the popup window (if used), in
pixels.
-id_button string input#mkwsButton (Never change this.)
+popup_button string input.mkwsButton (Never change this.)
-id_popup string #mkwsPopup (Never change this.)
----
+popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1
-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:
+popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1
- <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
- - -
-Copyright (C) 2013 by IndexData ApS, <http://www.indexdata.com>
+Copyright (C) 2013-2014 by IndexData ApS, <http://www.indexdata.com>
projects / mkws-moved-to-github.git / blobdiff