MKWS demo client

`s with well-known MKWS classes in any HTML page, the various components of an application @@ -47,14 +54,15 @@ 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 - - + +

@@ -63,10 +71,9 @@ The following is a complete MKWS-based searching application: 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 (and no, usually, you can't just load the file -directly from disk as some browsers, e.g Chrome, won't allow storing cookies). -Just like that, you have working metasearching. +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 --------------------- @@ -77,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. @@ -98,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 @@ -110,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: @@ -191,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 =========== @@ -206,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 ----------------- @@ -789,4 +862,4 @@ and .CLASS indicates an instance of a class. - - - -Copyright (C) 2013-2014 by Index Data ApS, +Copyright (C) 2013-2014 Index Data ApS.