Rework discussion.

[mkws-moved-to-github.git] / doc / mkws-developer.markdown

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index ffa831b..a299eeb 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -145,13 +145,13 @@ Widget specialisation (inheritance)
 -----------------------------------
 
 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
@@ -161,11 +161,11 @@ that you want to specialise from -- in this case, `Records` -- using
 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
@@ -180,7 +180,8 @@ that is passed into `registerWidgetType`'s callback function, and can
 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
@@ -188,7 +189,8 @@ be used by the derived widget.
        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
@@ -197,7 +199,7 @@ be used by the derived widget.
        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()` --
@@ -219,16 +221,6 @@ be used by the derived widget.
        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
@@ -237,20 +229,15 @@ be used by the derived widget.
        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
-example, the `Builder` widget uses a `callback` property as the
+example, the `builder` widget uses a `callback` property as the
 function that it use to publish the widget definition that it
 constructs. This defaults to the builtin function `alert`, but can be
-overridden by derived widgets such as `ConsoleBuilder`.
+overridden by derived widgets such as `console-builder`.
 
 
 Team methods
@@ -331,7 +318,7 @@ API should get simpler.
 Events
 ------
 
-TODO: list of events that can be usefully subscribed to.
+FIXME: list of events that can be usefully subscribed to.
 
 
 - - -