% The MasterKey Widget Set developer's guide
% Mike Taylor
-% 11 August 2014
+% November 2014
+
+
+Introduction
+============
+
+This manual is for people who want to build the widget set from
+source, develop the widget set's core code, or (more likely) create
+their own widgets as extensions to the main set.
+
+Those who want to use existing widgets should read
+[The MKWS manual: embedded metasearching with the MasterKey Widget
+Set](mkws-manual.html) instead.
+
+
+Required development tools
+==========================
+
+If you are building the widget set, you will need the following Debian
+packages (or their equivalents on your operating system):
+
+ $ sudo apt-get install curl git make unzip apache2 \
+ 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`.
Overview
`responsive_design_width`. Should be used for "unimportant"
widgets that can be omitted from the mobile version of a site.
-* TODO subwidget()
-
-* TODO expandValue()
+* `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
- - -
-Copyright (C) 2013-2014 by IndexData ApS, <http://www.indexdata.com>
+Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>