% 11 August 2014
+Required development tools
+==========================
+
+If you are building the widget set, as opposed to just using it, you
+will need the following Debian packages (or their equivalents on your
+operating system):
+
+ $ sudo apt-get install curl git pandoc yui-compressor libbsd-resource-perl
+
+You also need Node.js, but unfortunately the `node-js` package is not
+available for Debian wheezy. You can either get it from
+wheezy-backports or download the source from
+http://nodejs.org/download/ and build it yourself. You need both Node
+itself and its package manager NPM: `make install` puts them into
+`/usr/local/bin`.
+
+To compile the default templates you'll need to install the stable
+version of Handlebars. Currently it's at 2.0.0 and available by npm:
+
+ $ npm install handlebars@2.0.0 -g
+
+
Overview
========
* `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
------------
* `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
* `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.
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>
+Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>