New section on four-layer structure of the code.

[mkws-moved-to-github.git] / doc / mkws-developer.markdown

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index ade8da5..9d3ac4b 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -3,12 +3,23 @@
 % November 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
 ==========================
 
 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 make unzip apache2 \
            pandoc yui-compressor libbsd-resource-perl
 
        $ sudo apt-get install curl git make unzip apache2 \
            pandoc yui-compressor libbsd-resource-perl

@@ -20,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`.
 
 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
 
 Development with MKWS consists primarily of defining new types of
 widgets. These can interact with the core functionality is several