s/TODO/FIXME/

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

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index 9d3ac4b..edc2566 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -87,29 +87,30 @@ Defining new types of widget
 ----------------------------
 
 Development with MKWS consists primarily of defining new types of
 ----------------------------
 
 Development with MKWS consists primarily of defining new types of

-widgets. These can interact with the core functionality is several
-defined ways.
+widgets. This is done using exactly the same API as the the widgets
+that come as part of the set: they have no privileged access.

 
 You create a new widget type by calling the `mkws.registerWidgetType`
 function, passing in the widget name and a function. The name is used
 to recognise HTML elements as being widgets of this type -- for
 
 You create a new widget type by calling the `mkws.registerWidgetType`
 function, passing in the widget name and a function. The name is used
 to recognise HTML elements as being widgets of this type -- for

-example, if you register a `Foo` widget, elements like
-`<div class="mkwsFoo">` will be widgets of this type.
+example, if you register a `foo` widget, elements like
+`<div class="mkws-foo">` will become widgets of this type.

 
 

-The function promotes a bare widget object (passed as `this`) into a
+The function promotes a bare widget object (which is created by the
+core widget code and passed in as `this`) into a

 widget of the appropriate type. MKWS doesn't use classes or explicit
 prototypes: it just makes objects that have the necessary
 behaviours. There are _no_ behaviours that Widgets are obliged to
 provide: you can make a doesn't-do-anything-at-all widget if you like:
 
 widget of the appropriate type. MKWS doesn't use classes or explicit
 prototypes: it just makes objects that have the necessary
 behaviours. There are _no_ behaviours that Widgets are obliged to
 provide: you can make a doesn't-do-anything-at-all widget if you like:
 

-       mkws.registerWidgetType('Sluggard', function() {});
+       mkws.registerWidgetType('sluggard', function() {});

 
 More commonly, widgets will subscribe to one or more events, so that
 they're notified when something interesting happens. For example, the
 
 More commonly, widgets will subscribe to one or more events, so that
 they're notified when something interesting happens. For example, the

-`Log` widget asks to be notified when a `log` event happens, and
+`log` widget asks to be notified when a `log` event happens, and

 appends the logged message to its node, as follows:
 
 appends the logged message to its node, as follows:
 

-       mkws.registerWidgetType('Log', function() {
+       mkws.registerWidgetType('log', function() {

          var that = this;
 
          this.team.queue("log").subscribe(function(teamName, timestamp, message) {
          var that = this;
 
          this.team.queue("log").subscribe(function(teamName, timestamp, message) {

@@ -131,11 +132,11 @@ This simple widget illustrates several important points:
 * You can add functionality to a widget by subscribing it to an
   event's queue using `this.team.queue("EVENT").subscribe`. The
   argument is a function which is called whenever the event is
 * You can add functionality to a widget by subscribing it to an
   event's queue using `this.team.queue("EVENT").subscribe`. The
   argument is a function which is called whenever the event is

-  published. The arguments to the function are different for different
-  events.
+  published. The arguments to the event-callback function are
+  different for different events.

 
 * As with so much JavaScript programming, the value of the special
 
 * As with so much JavaScript programming, the value of the special

-  variable `this` is lost inside the `subscribez` callback function,
+  variable `this` is lost inside the `subscribe` callback function,

   so it must be saved if it's to be used inside that callback
   (typically as a local variable named `that`).
 
   so it must be saved if it's to be used inside that callback
   (typically as a local variable named `that`).
 

@@ -144,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

@@ -160,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

@@ -226,7 +227,7 @@ be used by the derived widget.
        widgets that can be omitted from the mobile version of a site.
 
 * `expandValue()` --
        widgets that can be omitted from the mobile version of a site.
 
 * `expandValue()` --

-       TODO: either document this or remove it from the API.
+       FIXME: either document this or remove it from the API.

 
 * `subwidget(type, overrides, defaults)` --
        Returns the HTML of a subwidget of the specified type, which
 
 * `subwidget(type, overrides, defaults)` --
        Returns the HTML of a subwidget of the specified type, which

@@ -241,7 +242,7 @@ be used by the derived widget.
        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
        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,
        widget and everything related to it.
 
 In addition to these properties and methods of the bare widget object,

@@ -330,7 +331,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.

 
 
 - - -
 
 
 - - -