`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. @@ -57,17 +57,16 @@ The following is a complete MKWS-based searching application: -

-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 (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. How the example works --------------------- @@ -192,6 +191,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 +307,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 ----------------- @@ -482,7 +547,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 @@ -620,9 +685,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"]] @@ -701,19 +766,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 ---- @@ -790,4 +855,4 @@ and .CLASS indicates an instance of a class. - - - -Copyright (C) 2013-2014 by IndexData ApS, +Copyright (C) 2013-2014 by Index Data ApS,