-----------------------------------
Many widgets are simple specialisations of existing widgets. For
-example, the `Record` widget is the same as the `Records` widget
-except that it defaults to displaying a single record. It's defined as
-follows:
+example, the `images` widget is the same as the `records` widget
+except that it defaults to using the `images` template for displaying
+its result list. It's defined as follows:
- mkws.registerWidgetType('Record', function() {
- mkws.promotionFunction('Records').call(this);
- if (!this.config.maxrecs) this.config.maxrecs = 1;
+ mkws.registerWidgetType('images', function() {
+ mkws.promotionFunction('records').call(this);
+ if (!this.config.template) this.config.template = 'images';
});
Remember that when a promotion function is called, it's passed a base
the promotion function that's been registered for that type.
Once this has been done, the specialisations can be introduced. In
-this case, it's a very simple matter of changing the `maxrecs`
-configuration setting to 1 unless it's already been given an explicit
-value. (That would occur if the HTML used an element like `<div
-class="mkwsRecord" maxrecs="2">`, though it's not obvious why anyone
-would do that.)
+this case, it's a very simple matter of changing the `template`
+configuration setting to `'images'` unless it's already been given an
+explicit value. (That would occur if the HTML used an element like
+`<div class="mkws-images" template="my-images">` to use a customised
+template.
Reference Guide
be used by the derived widget.
* `String this.type` --
- A string containing the type of the widget.
+ A string containing the type of the widget (`search`,
+ `switch`, etc.)
* `Team this.team` --
The team object to which this widget belongs. The team has
below.
* `DOMElement this.node` --
- The DOM element of the widget
+ The DOM element of the widget. Most often used for inserting
+ HTML into the widget element.
* `Hash this.config` --
A table of configuration values for the widget. This table
inherits from the default configuration. Instances of widgets
in HTML can set configuration items as HTML attributes: for
example, the HTML element
- `<div class="mkwsRecords" maxrecs="10">`.
+ `<div class="mkwsRecords" maxrecs="10">`
creates a widget for which `this.config.maxrecs` is set to 10.
* `String this.toString()` --
widgets such as `Records` and `Facet` that display some part
of a search result.
-* `VOID hideWhenNarrow()` --
- Registers that this widget should hide itself when the page
- becomes "narrow" -- that is, fewer pixels in width that the
- threshhold value specified by the top-level configuration item
- `responsive_design_width`. Should be used for "unimportant"
- widgets that can be omitted from the mobile version of a site.
-
-* `expandValue()` --
- TODO: either document this or remove it from the API.
-
* `subwidget(type, overrides, defaults)` --
Returns the HTML of a subwidget of the specified type, which
can then be inserted into the widget using the
See for example the `Credo` widget defined in the example
area's `mkws-widget-credo.js` file. This uses several
invocations of `subwidget` to create a complex compound widget
- with numerous text, facet and image panes. TODO: rename this
+ with numerous text, facet and image panes. FIXME: rename this
widget and everything related to it.
In addition to these properties and methods of the bare widget object,
Events
------
-TODO: list of events that can be usefully subscribed to.
+FIXME: list of events that can be usefully subscribed to.
- - -