Use the LGPL instead of the GPL.

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

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index 20ad83a..00a5b59 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -134,6 +134,46 @@ be used by the derived widget.
 * `String this.value()` --
        A function returning the value of the widget's HTML element.
 
+* `VOID autosearch()` --
+       Registers that this kind of widget is one that requires an
+       automatic search to be run for it if an `autosearch` attribute
+       is provided on the HTML element. This is appropriate for
+       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
+       `this.node.html` function. The subwidget is given the same
+       attributes at the parent widget that invokes this function,
+       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.
+
+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
+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`.
+
 
 Team methods
 ------------
@@ -148,9 +188,10 @@ properties.
 * `Num team.totalRecordCount()`
 * `Num team.currentPage();`
 * `String team.currentRecordId()`
-* `String team.currentRecordData()` --
-       Simple accessor functions that provide the ability to read
-       properties of the team.
+* `String team.currentRecordData()`
+
+These are all simple accessor functions that provide the ability to
+read properties of the team.
 
 * `Array team.filters()` --
        Another accessor function, providing access to the array of
@@ -162,15 +203,15 @@ properties.
 
 * `Bool team.targetFiltered(targetId)` --
        Indicates whether the specified target has been filtered by
-       selection as a facet.
+       selection as a facet. This is used only by the `Facet` widget,
+       and there is probably no reason for you to use it.
 
 * `Hash team.config()` --
        Access to the team's configuration settings. There is almost
        certainly no reason to use this: the settings that haven't
        been overridden are accessible via `this.config`.
 
-* `Void team.set_sortOrder(string)`
-* `Void team.set_perpage(number)` --
+* `Void team.set_sortOrder(string)`, `Void team.set_perpage(number)` --
        "Setter" functions for the team's sortOrder and perpage
        functions. Unlikely to be needed outside of the `Sort` and
        `Perpage` widgets.
@@ -208,6 +249,13 @@ infelicities reflect the fact that some code that rightly belongs in
 widgets is still in the team. When we finish migrating it, the widget
 API should get simpler.
 
+
+Events
+------
+
+TODO: list of events that can be usefully subscribed to.
+
+
 - - -
 
 Copyright (C) 2013-2014 by IndexData ApS, <http://www.indexdata.com>