X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-developer.markdown;h=9d3ac4b72ed7151ec5d85556e9f8d1a9cc0d5b70;hb=c209fd276576df2500e25299a00120db4c573884;hp=f4b991925888ef192f73f1ed69d0788be0181506;hpb=a0c0f775b4ae1fdbc6f5b661175fe4f437b0a45c;p=mkws-moved-to-github.git

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index f4b9919..9d3ac4b 100644
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -1,16 +1,28 @@
 % 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, as opposed to just using it, you
-will need the following Debian packages (or their equivalents on your
-operating system):
+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 pandoc yui-compressor libbsd-resource-perl
+	$ 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
@@ -19,17 +31,60 @@ 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
+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`.
 
 
-Overview
-========
 
-Core concepts
--------------
+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
@@ -280,4 +335,4 @@ TODO: list of events that can be usefully subscribed to.
 
 - - -
 
-Copyright (C) 2013-2014 by Index Data ApS, <http://www.indexdata.com>
+Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>