X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-developer.markdown;h=d944a6efed641c0cc557c90759a871c733d752ef;hb=7a06e9e971a22f99930bc8ec817737dd11906095;hp=f0340a2cfee4c6ab6a73f97e138d4f47a2064ba5;hpb=bc3f59298d3a037d1e8b719e525db700ecc893bd;p=mkws-moved-to-github.git diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown index f0340a2..d944a6e 100644 --- a/doc/mkws-developer.markdown +++ b/doc/mkws-developer.markdown @@ -1,38 +1,135 @@ % 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 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`. + + + +Event passing ------------- +The primary method of communication between components of the widget +set -- specifically, between teams and their widgets -- is event +passing. Widgets subscribe to named events; when something relevant +happens (such as the reception of a message from metasearch +middleware), the event is published, along with the relevant data. All +widgets that susbcribed to the event are then notified, and can take +appropriate action. + +Different kinds of events have different data associated with +them. This data is passed when the event is published, and so is made +available to the subscribing code. + +The possible events, and their associated data, are described +[below](#events). + + +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 -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 -example, if you register a `Foo` widget, elements like -`