-----------------------------------
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
except where overrides are passed in. If defaults are also
provided, then these are used when the parent widget provides
no values. Both the `overrides` and `defaults` arguments are
- hashes: the latter is optional.
-
- 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
- widget and everything related to it.
+ hashes: the latter is optional. This can be used to assemble
+ compound widgets containing several subwidgets.
In addition to these properties and methods of the bare widget object,
some kinds of specific widget add other properties of their own. For
Events
------
-TODO: list of events that can be usefully subscribed to.
+FIXME: list of events that can be usefully subscribed to.
- - -