The following is
[a complete MKWS-based searching application](//example.indexdata.com/simple.html):
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>MKWS demo client</title>
- <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
- <link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
- </head>
- <body>
- <div class="mkws-search"></div>
- <div class="mkws-results"></div>
- </body>
- </html>
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>MKWS demo client</title>
+ <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
+ <link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
+ </head>
+ <body>
+ <div class="mkws-search"></div>
+ <div class="mkws-results"></div>
+ </body>
+ </html>
Go ahead, try it! Simply put the above in a file (e.g index.html),
drop it into a folder accessible with an ordinary web-server (e.g
To see all of these working together, just put them all into the HTML
`<body>` like so:
- <div class="mkws-switch"></div>
- <div class="mkws-lang"></div>
- <div class="mkws-progress"></div>
- <div class="mkws-search"></div>
- <div class="mkws-results"></div>
- <div class="mkws-targets"></div>
- <div class="mkws-stat"></div>
+ <div class="mkws-switch"></div>
+ <div class="mkws-lang"></div>
+ <div class="mkws-progress"></div>
+ <div class="mkws-search"></div>
+ <div class="mkws-results"></div>
+ <div class="mkws-targets"></div>
+ <div class="mkws-stat"></div>
The full set of supported widgets is described in the
-reference guide below.
+reference guide
+[below](#widgets).
Widget team
-----------
parameters into the `mkws_config` object. So the HTML header looks
like this:
- <script type="text/javascript">
- var mkws_config = {
- lang_options: [ "en", "da" ]
- lang: "da",
- sort_default: "title",
- query_width: 60
- };
- </script>
- <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
+ <script type="text/javascript">
+ var mkws_config = {
+ lang_options: [ "en", "da" ]
+ lang: "da",
+ sort_default: "title",
+ query_width: 60
+ };
+ </script>
+ <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
This configuration restricts the set of available UI languages English
and Danish (omitting German), sets the default to Danish (rather than
`type="text/x-handlebars-template"` attribute. For example, to override the
pager template you would include this in your document:
- <script class="mkws-template-pager" type="text/x-handlebars-template">
- ...new Pager template
- </script>
+ <script class="mkws-template-pager" type="text/x-handlebars-template">
+ ...new Pager template
+ </script>
The Facet template has a special feature where you can override it on
a per-facet basis by adding a dash and the facet name as a suffix eg.
this to work you'll need to enable verbose output from Handlebars which is done
by including this line or similar:
- <script>Handlebars.logger.level = 1;</script>
+ <script>Handlebars.logger.level = 1;</script>
Internationalisation
--------------------
the source via the address provided in the metadata as the first
element of `md-electronic-url`:
- <script class="mkws-template-summary" type="text/x-handlebars-template">
- <a href="{{md-electronic-url.[0]}}">
- <b>{{md-title}}</b>
- </a>
- {{#if md-title-remainder}}
- <span>{{md-title-remainder}}</span>
- {{/if}}
- {{#if md-title-responsibility}}
- <span><i>{{md-title-responsibility}}</i></span>
- {{/if}}
- </script>
+ <script class="mkws-template-summary" type="text/x-handlebars-template">
+ <a href="{{md-electronic-url.[0]}}">
+ <b>{{md-title}}</b>
+ </a>
+ {{#if md-title-remainder}}
+ <span>{{md-title-remainder}}</span>
+ {{/if}}
+ {{#if md-title-responsibility}}
+ <span><i>{{md-title-responsibility}}</i></span>
+ {{/if}}
+ </script>
For a more involved example where markup for multiple widgets is decorated with
[Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is
in a popup. The key part of such an application is this invocation of
the MKWS jQuery plugin:
- <div class="mkws-search"></div>
- <div class="mkws-popup" popup_width="1024" popup_height="650">
- <div class="mkws-results"></div>
- </div>
+ <div class="mkws-search"></div>
+ <div class="mkws-popup" popup_width="1024" popup_height="650">
+ <div class="mkws-results"></div>
+ </div>
The necessary scaffolding can be seen in an example application,
[popup.html](http://example.indexdata.com/popup.html).
if multiple Referring URLs are needed, then each must be specified in
its own User Access record.
-### Tell the application to use the library
-
-In the HTML of the application, tell MKWS to authenticate on to the
-Service Proxy. When referer-based or IP-based authentication is used,
-this is very simple:
-
- <script type="text/javascript">
- var mkws_config = { service_proxy_auth:
- "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
- </script>
-
-> TODO This should be the default setting: see **MKWS-251**.
-
-And ensure that access to the MWKS application is from the correct
-Referrer URL or IP-range.
-
### (Optional): embed credentials for access to the library
When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
-Proxy when establishing the session. This can most simply be done just
-by setting the `service_proxy_auth` configuration item to a URL such as
-`//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish`
+Proxy when establishing the session. This is done
+by setting the `sp_auth_credentials` configuration item to a string
+containing the username and password separated by a slash:
-> TODO It should be possible to add the username and password to the
-> configuration without needing to repeat the rest of the URL: see
-> **MKWS-254**.
+ mkws_config = { sp_auth_credentials: "mike/swordfish" };
### (Optional): conceal credentials from HTML source
-Using a credential-based Service-Proxy authentication URL such as the
-one above reveals the the credentials to public view -- to anyone who
-does View Source on the MKWS application. This may be acceptable for
-some libraries, but is intolerable for those which provide
-authenticated access to subscription resources.
-
-In these circumstances, a more elaborate approach is necessary. The
-idea is to make a URL local to the customer that is used for
-authentication onto the Service Proxy, hiding the credentials in a
-local rewrite rule. Then local mechanisms can be used to limit access
-to that local authentication URL. Here is one way to do it when
+Using credential-based authentication settings such as those above
+reveals the the credentials to public view -- to anyone who does View
+Source on the MKWS application. This may be acceptable for some
+libraries, but is intolerable for those which provide authenticated
+access to subscription resources.
+
+In these circumstances, a different approach is
+necessary. Referer-based or IP-based authentication may be
+appropriate. But if these are not possible, then a more elaborate
+approach can be used to hide the credentials in a web-server
+configuration that is not visible to users.
+
+The idea is to make a Service Proxy authentication URL local to the
+customer, hiding the credentials in a rewrite rule in the local
+web-server's configuration. Then local mechanisms can be used to limit
+access to that local authentication URL. Here is one way to do it when
Apache2 is the application's web-server, which we will call
-yourname.com:
+yourname.com`:
Step 1: add a rewriting authentication alias to the configuration:
RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
Step 2: set the MKWS configuration item `service_proxy_auth` to
-<http://yourname.com/spauth/>
+`http://yourname.com/spauth/`.
-Step 3: protect access to the local path <http://yourname.com/spauth/>
+Step 3: protect access to the local path `http://yourname.com/spauth/`
(e.g. using a `.htaccess` file).
Reference guide
===============
+Widgets
+-------
+
+The following widgets are provided in the core set. (Others can be
+added: see the [MKWS developers' guide](mkws-developer.html).)
+
+----
+Name Description
+---- -----------
+`auth-name` Initially empty, it updates itself to shows the name
+ of the library that the application is logged in as
+ when authentication is complete.
+
+`builder` A button which, when pressed, analyses the current
+ settings of the team that it is a part of, and
+ generates the HTML for an auto-searching element
+ that will replicate the present search. This HTML is
+ displayed in an alert box: it is intended that this
+ widget be subclassed to store the generated widget
+ definitions in more useful places.
+
+`categories` Obtains from the Service Proxy a list of the target
+ categories associated with the library in use, and
+ displays them in a drop-down list. When a category
+ is selected, searches are limited to the targets
+ that are part of that category.
+
+`config` This widget has no functionality of its own, but its
+ configuration is copied up into its team, allowing
+ it to affect other widgets in the team. This is the
+ only way to set configuration items at the team
+ level.
+
+`console-builder` Like the `builder` widget, but emits the generated
+ HTML on the JavaScript console. This exists to
+ provide an example of how to subclass the `builder`
+ widget.
+
+`cover-art` Displays cover art for a book by searching in
+ Amazon. Often used with an `autosearch` attribute to
+ indicate what book to display. For example,
+ `<div class="mkws-cover-art" autosearch="isbn=1291177124"></div>`
+ displays cover art for _All Yesterdays: Unique and
+ Speculative Views of Dinosaurs and Other Prehistoric
+ Animals_.
+ For this widget to work, a library that includes the
+ AmazonBooks target must be used. For example, the
+ "DEMO AmazonBooks for MKWS" account, which can be
+ selected with `sp_auth_credentials="mkws-amazon/mkws"`.
+
+`details` This widget is generated by the toolkit itself to
+ hold the full details of records that are initially
+ listed in summary form.
+
+`done` Initially empty, this widget is set to display
+ "Search complete: found _n_ records" when all
+ targets have completed their work, either returning
+ a hit-count or an error. The message displayed can
+ be changed by overriding the `done` template using
+ `<script class="mkws-template-done" type="text/x-handlebars-template">`.
+
+`facet` x
+
+`google-image` x
+
+`images` x
+
+`lang` x
+
+`log` x
+
+`lolcat` x
+
+`motd-container` x
+
+`motd` x
+
+`navi` x
+
+`pager` x
+
+`per-page` x
+
+`progress` x
+
+`query` x
+
+`ranking` x
+
+`record` x
+
+`records` x
+
+`reference` x
+
+`results` x
+
+`search-form` x
+
+`search` x
+
+`sort` x
+
+`stat` x
+
+`switch` x
+
+`targets` x
+
+`termlists` x
+----
+
+
Configuration object
--------------------
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 ...
- }
- }
+ var mkws_config = {
+ language_French: {
+ "Authors": "Auteurs",
+ "Subjects": "Sujets",
+ // ... and others ...
+ }
+ }
The following strings occurring in the UI can be translated:
`Displaying`,
toolkit are used, so it's necessary to include both CSS and JavaScript
from that toolkit. The relevant lines are:
- <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" />
+ <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" />
- <div class="mkws-search"></div>
- <div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
- <div class="mkws-switch"></div>
- <div class="mkws-lang"></div>
- <div class="mkws-results"></div>
- <div class="mkws-targets"></div>
- <div class="mkws-stat"></div>
- </div>
+ <div class="mkws-search"></div>
+ <div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
+ <div class="mkws-switch"></div>
+ <div class="mkws-lang"></div>
+ <div class="mkws-results"></div>
+ <div class="mkws-targets"></div>
+ <div class="mkws-stat"></div>
+ </div>
----
Element Type Default Description
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
+ #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
- - -
projects / mkws-moved-to-github.git / blobdiff