<link rel="stylesheet" href="//mkws.indexdata.com/mkws.css" />
</head>
<body>
- <div class="mkwsSearch"></div>
- <div class="mkwsResults"></div>
+ <div class="mkws-search"></div>
+ <div class="mkws-results"></div>
</body>
</html>
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, `<div>` 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 widgets: a search box and a
-results area. But more are supported. The main widgets are:
+results area. But more are supported.
+
+Defining Widget Elements
+========================
+
+Widget type
+-----------
-* `mkwsSearch` -- provides the search box and button.
+An HTML element is made an MKWS widget by including an MKWS
+class-name. These names begin `mkws-`: what follows that prefix
+specifies the type of the widget. The type can be any sequence of
+alphanumeric characters and hyphens _except_ something beginning
+`team` -- see below.
-* `mkwsResults` -- provides the results area, including a list of
+The main widgets are:
+
+* `mkws-search` -- provides the search box and button.
+
+* `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.
-* `mkwsStat` --provides a status line summarising the statistics of
+* `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.
-* `mkwsLang` -- provides links to switch between one of several
+* `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
`<body>` like so:
- <div id="mkwsSwitch"></div>
- <div id="mkwsLang"></div>
- <div id="mkwsSearch"></div>
- <div id="mkwsResults"></div>
- <div id="mkwsTargets"></div>
- <div id="mkwsStat"></div>
+ <div id="mkws-switch"></div>
+ <div id="mkws-lang"></div>
+ <div id="mkws-progress"></div>
+ <div id="mkws-search"></div>
+ <div id="mkws-results"></div>
+ <div id="mkws-targets"></div>
+ <div id="mkws-stat"></div>
The full set of supported widgets is described in the
reference guide below.
+Widget team
+-----------
+
+In general a set of widgets work together in a team: in the example
+above, the search-term that the user enters in the `mkws-search`
+widget is used to generate the set of records that are displayed in
+the `mkws-results` widget.
+
+Sometimes, it's desirable to have multiple teams in a single page. A
+widget can be placed in a named team by giving it (in addition to its
+main class) a class that begins with `mkws-team-`: what follows that
+prefix specifies the team that the widget is part of. For example,
+`<div class="mkws-search mkws-team-aux">` creates a search widget that
+is part of the `aux` team.
+
+Widgets that do not have a team specified (as in the examples above)
+are placed in the team called `AUTO`.
+
+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`. And the classes
+used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be
+`mkwsTeam_foo`.
+
+The 1.x series of MKWS releases recognise these old-style class-names
+as well as the canonical ones, 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
=============
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;).
+repository](http://git.indexdata.com/?p=mkws.git;a=tree;f=src/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
--------------------
To override the template for a widget, include it inline in the document
-as a `<script>` tag marked with a class of `mkwsTemplate_Foo` where Foo is the
+as a `<script>` tag marked with a class of `mkws-template-foo` where foo is the
name of the template you want to override (typically the name of the widget).
Inline Handlebars templates are distinguished from Javascript via a
`type="text/x-handlebars-template"` attribute. For example, to override the
-Pager template you would include this in your document:
+pager template you would include this in your document:
- <script class="mkwsTemplate_Pager" type="text/x-handlebars-template">
+ <script class="mkws-template-pager" type="text/x-handlebars-template">
...new Pager template
</script>
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, `<div class="mkwsPager" template="specialPager"/>`.
+for example, `<div class="mkws-pager" template="special-pager"/>`.
Templates for MKWS can also be
[precompiled](http://handlebarsjs.com/precompilation.html). If a precompiled
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`:
- <script class="mkwsTemplate_Records" type="text/x-handlebars-template">
+ <script class="mkws-template-records" type="text/x-handlebars-template">
{{#each hits}}
<div class="{{containerClass}}">
<a href="{{md-electronic-url.[0]}}">
projects / mkws-moved-to-github.git / blobdiff