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
 -----------------------------------
 
 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
        });
 
 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
 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
 
 
 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` --
 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
 
 * `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` --
        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
 
 * `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
        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()` --
        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.
 
        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
 * `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
        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
 
 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
 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
 
 
 Team methods

@@ -331,7 +318,7 @@ API should get simpler.
 Events
 ------
 
 Events
 ------
 

-TODO: list of events that can be usefully subscribed to.
+FIXME: list of events that can be usefully subscribed to.

 
 
 - - -
 
 
 - - -