X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=ef54044e2313aeed74b6a008144934cddf0e28e9;hb=22c49596b24a5e05c9940e17546b7e2b67eb1fc7;hp=b920dc860a4010d394d1d492762a83abf6ffe2d8;hpb=27cbd8d3e1f9067688d9d6a7a934a7ecd1f14955;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index b920dc8..ef54044 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -128,10 +128,10 @@ The main widgets are: * `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. + meaningful when `mkws-targets` is also provided. * `mkws-targets` -- the area where per-target information will appear - when selected by the link in the `mkwsSwitch` area. Of interest + when selected by the link in the `mkws-switch` area. Of interest mostly for fault diagnosis rather than for end-users. * `mkws-lang` -- provides links to switch between one of several @@ -256,29 +256,29 @@ quotes must be used to contain the entire attribute value.) Control over HTML and CSS ========================= -More sophisticated applications will not simply place the `
`s +More sophisticated applications will not simply place the widgets together, but position them carefully within an existing page framework -- such as a Drupal template, an OPAC or a SharePoint page. While it's convenient for simple applications to use a monolithic -`mkwsResults` area which contains record, facets, sorting options, +`mkws-results` area which contains record, facets, sorting options, etc., customised layouts may wish to treat each of these components -separately. In this case, `mkwsResults` can be omitted, and the +separately. In this case, `mkws-results` can be omitted, and the following lower-level widgets provided instead: -* `mkwsTermlists` -- provides the facets +* `mkws-termlists` -- provides the facets -* `mkwsRanking` -- provides the options for how records are sorted and +* `mkws-ranking` -- provides the options for how records are sorted and how many are included on each page of results. -* `mkwsPager` -- provides the links for navigating back and forth +* `mkws-pager` -- provides the links for navigating back and forth through the pages of records. -* `mkwsNavi` -- when a search result has been narrowed by one or more +* `mkws-navi` -- when a search result has been narrowed by one or more facets, this area shows the names of those facets, and allows the selected values to be clicked in order to remove them. -* `mkwsRecords` -- lists the actual result records. +* `mkws-records` -- lists the actual result records. Customisation of MKWS searching widgets can also be achieved by overriding the styles set in the toolkit's CSS stylesheet. The default @@ -326,14 +326,17 @@ pager template you would include this in your document: ...new Pager template -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="mkws-template-facet-subjects"`) +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`. (So `class="mkws-template-facet-subjects"`.) When +rendering a facet for which no specific template is defined, the code +falls back to using the generic facet template, just called `facet`. -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, `
`. +You can also explicitly specify a different template for a particular +instance of a widget by providing the name of your alternative +(eg. `special-pager`) 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 @@ -343,10 +346,10 @@ 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. +MKWS makes requests to the 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. 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 @@ -368,24 +371,21 @@ output locale specific text via the mkws-translate helper like so: 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 @@ -394,8 +394,8 @@ employed, take a look at the source of [topic.html](http://example.indexdata.com/topic.html?q=water). -Refinements -=========== +Some Refinements +================ Message of the day @@ -404,9 +404,9 @@ Message of the day Some applications might like to open with content in the area that will subsequently be filled with result-records -- a message of the day, a welcome message or a help page. This can be done by placing an -`mkwsMOTD` division anywhere on the page. It will be moved into the -`mkwsResults` area and initially displayed, but will be hidden when a -search is made. +`mkws-motd` division anywhere on the page. It will initially be moved +into the `mkws-results` area and displayed, but will be hidden as soon +as the first search is made. Popup results with jQuery UI @@ -418,17 +418,17 @@ 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: -
-
-
-
-
-
-
+
+
+
+
+
+
+
The necessary scaffolding can be seen in an example application, -http://example.indexdata.com/index-popup.html +[popup.html](http://example.indexdata.com/popup.html). Authentication and target configuration @@ -442,7 +442,7 @@ on the same MKWS server, so no explicit configuration is needed. In order to search in a customised set of targets, including subscription resources, it's necessary to create an account with -Index Data's hosted service proxy, and protect that account with +Index Data's hosted Service Proxy, and protect that account with authentication tokens (to prevent unauthorised use of subscription resources). For information on how to do this, see the next section. @@ -465,7 +465,7 @@ available targets to use. Maintaining the library ----------------------- -The service proxy accesses sets of targets that are known as +The Service Proxy accesses sets of targets that are known as "libraries". In general, each customer will have their own library, though some standard libraries may be shared between many customers -- for example, a library containing all open-access academic journals. @@ -664,7 +664,7 @@ For example, a `Records` widget can be limited to searching only in targets that have been categorised as news sources by providing an attribute as follows: -
+
Reference guide @@ -684,7 +684,7 @@ reasonably narrow. ---- Element Type Default Description -------- ----- --------- ------------ -debug_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with +log_level int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with datestamps, 3 = messages with datestamps and stack-traces. facets array *Note 1* Ordered list of names of facets to display. Supported facet names are @@ -747,7 +747,7 @@ use_service_proxy bool true If true, then a Service Proxy is use Perhaps we should get rid of the `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration items, and simply display the relevant menus -only when their containers are provided -- e.g. an `mkwsLang` element +only when their containers are provided -- e.g. an `mkws-lang` element for the language menu. But for now we retain these, as an easier route to lightly customise the display than my changing providing a full HTML structure. @@ -831,13 +831,13 @@ from that toolkit. The relevant lines are: -
-
-
-
-
-
-
+
+
+
+
+
+
+
---- @@ -865,7 +865,7 @@ 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 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 +element with class `mkws-termlists`, so as to avoid inadvertently styling other elements using the same class in the non-MKWS parts of the page. The HTML structure is as follows. As in CSS, #ID indicates a unique identifier