MKWS demo client

`s with well-known -identifiers in any HTML page, the various components of an application +MKWS classes in any HTML page, the various components of an application can be embedded: search-boxes, results areas, target information, etc. Simple Example ============== -The following is a complete MKWS-based searching application: +The following is +[a complete MKWS-based searching application](//example.indexdata.com/simple.html): MKWS demo client - - + + -

-Go ahead, try it! You don't even need a web-server. Just copy and -paste this HTML into a file on your computer -- `/tmp/magic.html`, -say -- and point your web-browser at it: -`file:///tmp/magic.html`. Just like that, you have working -metasearching. - +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 +Apache) and load it in your web browser. Just like that, you have +working metasearching. How the example works --------------------- @@ -78,7 +84,7 @@ you: the `` element at the top level contains a `` and a page, you can add MKWS elements. These fall into two categories. First, the prerequisites in the HTML -header, which are loaded from the tool site mkws.indexdata.com: +header, which are loaded from the tool site `mkws.indexdata.com`: * `mkws-complete.js` contains all the JavaScript needed by the widget-set. @@ -99,9 +105,8 @@ results area. But more are supported. The main `

`s are: paging for large results sets, facets for refining a search, sorting facilities, etc. -* `mkwsLang` -- provides links to switch between one of several - different UI languages. By default, English, Danish and German are - provided. +* `mkwsStat` --provides a status line summarising the statistics of + the various targets. * `mkwsSwitch` -- provides links to switch between a view of the result records and of the targets that provide them. Only @@ -111,8 +116,9 @@ results area. But more are supported. The main `

`s are: when selected by the link in the `mkwsSwitch` area. Of interest mostly for fault diagnosis rather than for end-users. -* `mkwsStat` --provides a status line summarising the statistics of - the various targets. +* `mkwsLang` -- provides links to switch between one of several + different UI languages. By default, English, Danish and German are + provided. To see all of these working together, just put them all into the HTML `` like so: @@ -192,6 +198,107 @@ containers. The structures used by the widget-set are described in the reference guide below. +Customised display using Handlebars templates +============================================= + +A lot can be done by styling widgets in CSS and changing basic MKWS config +options. For further customisation, MKWS allows you to change the markup it +outputs for any widget. This is done by overriding the +[Handlebars](http://handlebarsjs.com/) template used to generate it. In general +these consist of `{{things in double braces}}` that are replaced by values from +the system. For details of Handlebars template syntax, see [the online +documentation](http://handlebarsjs.com/). + +The templates used by the core widgets can be viewed in [our git +repository](http://git.indexdata.com/?p=mkws.git;a=tree;f=src/mkws.templates;). +Parameters are documented in a comment at the top of each template so +you can see what's going where. If all you want to do is add a CSS class to +something or change a `span` to a `div` it's easy to just copy the existing +template and make your edits. + +Overriding templates +-------------------- + +To override the template for a widget, include it inline in the document +as a ` + +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. +`Facet-Subjects` rather than `Facet`. (So `class="mkwsTemplate_Facet-Subjects"`) + +You can also explicitly specify a different template for a particular instance +of a widget by providing the name of your alternative (eg. SpecialPager) as the +value of the `template` key in the MKWS config object for that widget: +for example, `

`. + +Templates for MKWS can also be +[precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled +template of the same name is found in the `Handlebars.templates` object, it +will be used instead of the default. + +Inspecting metadata for templating +---------------------------------- + +MKWS makes requests to Service Proxy or Pazpar2 that perform the actual +searching. Depending on how these are configured and what is available from the +targets you are searching there may be more data available than what is +presented by the default templates. In this case, you can redefine the +`Record` template to include more fields in the full-record popup. + +Handlebars offers a convenient log helper that will output the contents of a +variable for you to inspect. This lets you look at exactly what is being +returned by the back end without needing to use a Javascript debugger. For +example, you might prepend `{{log hits}}` to the Records template in order to +see what is being returned with each search result in the list. In order for +this to work you'll need to enable verbose output from Handlebars which is done +by including this line or similar: + + + +Internationalisation +-------------------- + +If you would like your template to use the built in translation functionality, +output locale specific text via the mkws-translate helper like so: +`{{{mkws-translate "a few words"}}}`. + +Example +------- + +Rather than use the included AJAX helpers to render record details inline, +here's a Records template that will link directly to the source via the address +provided in the metadata as the first element of `md-electronic-url`: + + + +For a more involved example where markup for multiple widgets is decorated with +[Bootstrap](http://getbootstrap.com/) classes and a custom Handlebars helper is +employed, take a look at the source of +[topic.html](http://example.indexdata.com/topic.html?q=water). + + Refinements =========== @@ -207,41 +314,6 @@ day, a welcome message or a help page. This can be done by placing an 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 ----------------- @@ -431,7 +503,7 @@ this is very simple: "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" }; -> TODO This should be the default setting: see MKWS-251. +> 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. @@ -445,10 +517,11 @@ URL containing that hostname, such as `//yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` > TODO It should be possible to change just the hostname without -> needing to repeat the rest of the URL (protocol, path, query) +> needing to repeat the rest of the URL (protocol, path, query): see +> **MKWS-252**. > TODO When changing the SP authentication URL, the Pazpar2 URL should -> in general change along with it. +> in general change along with it: see **MKWS-253**. ### (Optional): embed credentials for access to the library @@ -459,7 +532,8 @@ 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` > TODO It should be possible to add the username and password to the -> configuration without needing to repeat the rest of the URL. +> configuration without needing to repeat the rest of the URL: see +> **MKWS-254**. ### (Optional): conceal credentials from HTML source @@ -480,7 +554,7 @@ yourname.com: Step 1: add a rewriting authentication alias to the configuration: RewriteEngine on - RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P] + 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 @@ -618,9 +692,9 @@ structure. 3. [10, 20, 30, 50] -4. http://mkws.indexdata.com/service-proxy-auth +4. http://sp-mkws.indexdata.com/service-proxy-auth -5. http://mkws.indexdata.com/service-proxy/ +5. http://sp-mkws.indexdata.com/service-proxy/ 6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]] @@ -699,19 +773,19 @@ from that toolkit. The relevant lines are:

---- -Element Type Default Description --------- ----- --------- ------------ -popup_width string 880 Width of the popup window (if used), in - pixels. +Element Type Default Description +-------- ----- ------- ------------ +popup_width string 880 Width of the popup window (if used), in + pixels. -popup_height string 760 Height of the popup window (if used), in - pixels. +popup_height string 760 Height of the popup window (if used), in + pixels. -popup_button string input.mkwsButton (Never change this.) +popup_button string `input.mkwsButton` (Never change this.) -popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1 +popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1 -popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1 +popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1 ---- @@ -788,4 +862,4 @@ and .CLASS indicates an instance of a class. - - - -Copyright (C) 2013-2014 by IndexData ApS, +Copyright (C) 2013-2014 Index Data ApS.