From c209fd276576df2500e25299a00120db4c573884 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Mon, 10 Nov 2014 16:55:59 +0000 Subject: [PATCH] New section on four-layer structure of the code. --- doc/mkws-developer.markdown | 54 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown index ed6c5d4..9d3ac4b 100644 --- a/doc/mkws-developer.markdown +++ b/doc/mkws-developer.markdown @@ -32,11 +32,59 @@ itself and its package manager NPM: `make install` puts them into `/usr/local/bin`. -Overview +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 -- 1.7.10.4