X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=79ae4d4b5913d62dcf64d9d94a5f657efcdc2702;hb=9ffc2065df69d0252bb711565425e5b18c1e9a49;hp=79e56d42fa0415160911948984678eef349360b7;hpb=672f0c5a1a2601a2b2688eb26ce56fb98e090724;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 79e56d4..79ae4d4 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -54,26 +54,26 @@ 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! 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 --------------------- @@ -84,61 +84,83 @@ 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. + contains all the JavaScript needed by the widget-set, including a + copy of the jQuery library. * `mkws.css` provides the default CSS styling Second, within the HTML body, `
` elements with special IDs that -begin `mkws` can be provided. These are filled in by the MKWS code, +begin `mkws-` can be provided. These are filled in by the MKWS code, and provide the components of the searching UI. The very simple -application above has only two such components: a search box and a -results area. But more are supported. The main `
`s are: +application above has only two such widgets: a search box and a +results area. But more are supported. + +Widget Elements +=============== + +The main widgets are: -* `mkwsSearch` -- provides the search box and button. +* `mkws-search` -- provides the search box and button. -* `mkwsResults` -- provides the results area, including a list of +* `mkws-results` -- provides the results area, including a list of brief records (which open out into full versions when clicked), 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. +* `mkws-progress` -- shows a progress bar indicating how many of the + targets have responded to the search request. + +* `mkws-stat` -- provides a status line summarising the statistics of + the various targets. -* `mkwsSwitch` -- provides links to switch between a view of the +* `mkws-switch` -- provides links to switch between a view of the result records and of the targets that provide them. Only meaningful when `mkwsTargets` is also provided. -* `mkwsTargets` -- the area where per-target information will appear +* `mkws-targets` -- the area where per-target information will appear 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. +* `mkws-lang` -- 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: -
-
-
-
-
-
+
+
+
+ +
+
+
+The full set of supported widgets is described in the +reference guide below. + +Old and new-style class-names +----------------------------- + +**NOTE.** Versions of MKWS before v1.0 used camel-case class-names: +without hyphens and with second and subsequent words capitalised. So +instead of `mkws-search`, it used to be `mkwsSearch`. The 1.x series +of MKWS versions also recognise these old-style class-names as a +facility for backwards compatibility. However, these **old class-names +are deprecated, and support will be removed in v2.0**. Existing +applications that use them should be upgraded to the new-style class +names as soon as convenient. Configuration ============= Many aspects of the behaviour of MKWS can be modified by setting -parameters into the `mkws_config` object. **This must be done *before* -including the MKWS JavaScript** so that when that code is executed it -can refer to the configuration values. So the HTML header looks like -this: +parameters into the `mkws_config` object. So the HTML header looks +like this: 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"`) +`facet-subjects` rather than `facet`. (So `class="mkws-template-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, `
`. +for example, `
`. Templates for MKWS can also be [precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled @@ -250,8 +273,7 @@ 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. +presented by the default templates. 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 @@ -277,7 +299,7 @@ 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`: - - -If individual result-related components are in use in place of the -all-in-one mkwsResults, then the redesigned application needs to -specify the locations where the termlists should appear in both -cases. In this case, wrap the wide-screen `mkwsTermlists` element in a -`mkwsTermlists-Container-wide` element; and provide an -`mkwsTermlists-Container-narrow` element in the place where the narrow-screen -termlists should appear. - - Popup results with jQuery UI ---------------------------- The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI) -can be used to construct MKWS applications in which the only component +can be used to construct MKWS applications in which the only widget generally visible on the page is a search box, and the results appear in a popup. The key part of such an application is this invocation of the MKWS jQuery plugin: @@ -795,7 +790,7 @@ The structure of the HTML generated by the MKWS widgets In order to override the default CSS styles provided by the MasterKey Widget Set, it's necessary to understand that structure of the HTML elements that are -generated within the components. This knowledge make it possible, for example, +generated within the widgets. This knowledge make it possible, for example, to style each `
` with class `term` but only when it occurs inside an element with ID `#mkwsTermlists`, so as to avoid inadvertently styling other elements using the same class in the non-MKWS parts of the page. @@ -862,4 +857,4 @@ and .CLASS indicates an instance of a class. - - - -Copyright (C) 2013-2014 by Index Data ApS, +Copyright (C) 2013-2014 Index Data ApS.