% The MasterKey Widget Set developer's guide
% Mike Taylor
-% 11 August 2014
+% November 2014
-Overview
+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`.
+
+
+Concepts
========
-Core concepts
--------------
+Code structure
+--------------
+
+The code of the widget set is in four main layers, described here from
+the bottom up:
+
+1. The core code, which manages the set of widget teams, default
+options, authentication onto the Service Proxy, and the creation of
+widgets from HTML elements.
+This code is in `mkws-core.js`
+
+2. The team code, which manages teams of widgets. This is responsible
+for the collections of widgets that make up teams, event queues, and
+handling search-and-retrieval events
+This code is in `mkws-team.js`
+
+3. The generic widget code, which handles the creation of widget
+objects, parsing configuration attributes from their HTML elements,
+and firing off automatic searches.
+
+4. The code for individual widgets, which is specific to those
+widgets. It often involves subscribing to events and responding to
+them by setting the HTML of the widget element, but need not do
+so. The code for many of the most important widgets is in
+`mkws-widget-main.js`, but certain other widgets are defined in other
+files beginning with the prefix `mkws-widget-`.
+
+In addition to this code, there are several source files containing
+support code:
+
+* `mkws-filter.js` contains support routine implementing the
+filter-set data structure, which contains information about which
+filters (e.g. by target, or by facet) are in force.
+
+* `mkws-handlebars.js` contains Handlebars helpers which can be used
+by the HTML templates.
+
+* `mkws-popup.js` defines a special widget for creating popup
+ windows. These may, but need not, contain other MKWS widgets,
+ forming a popup searching application.
+
+The final component of the source code is the set of Handlebars
+templates, in the `templates` directory, which are used to emit the
+HTML of the various widgets' contents. These are compiled into the
+file `mkws-templates.js`.
+
+
+
+Defining new types of widget
+----------------------------
Development with MKWS consists primarily of defining new types of
widgets. These can interact with the core functionality is several
* `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>
projects / mkws-moved-to-github.git / blobdiff