From: Mike Taylor <mike@indexdata.com>
Date: Wed, 9 Apr 2014 12:23:12 +0000 (+0100)
Subject: First bits of the developer guide.
X-Git-Tag: 1.0.0~974^2~10
X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=commitdiff_plain;h=0a481b1e53119da45c774874808f65821c2101aa;hp=f7484097c9c14d64fcfacd7c629f838af803fad6;p=mkws-moved-to-github.git

First bits of the developer guide.
---

diff --git a/doc/mkws-developer.txt b/doc/mkws-developer.txt
new file mode 100644
index 0000000..ec3ab7e
--- /dev/null
+++ b/doc/mkws-developer.txt
@@ -0,0 +1,45 @@
+Development with MKWS consists primarily of defining new types of
+widgets. These can interact with the core functionality is several
+defined ways.
+
+You cleare a new widget ttpe this 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 <div class="mkwsFoo"> will be widgets of this type.
+
+The function promotes a bare widget object (passed as `this') into a
+widget of the appropriate type. MKWS doesn't use classes or explicit
+prototypes: it just makes objects that have the necessary
+behaviours. Widgets have *no* behaviours that they have to provide:
+you can make a doesn't-do-anything-at-all widget if you like:
+
+	mkws.registerWidgetType('Sluggard', function() {});
+
+More commonly, widgets will subscribe to one or more events, so that
+they're notified when something interesting happens. For example, the
+"Log" widget asks to be notified when a "log" event happens, and
+appends the logged message to its node, as follows:
+
+	mkws.registerWidgetType('Log', function() {
+	    var that = this;
+
+	    this.team.queue("log").subscribe(function(teamName, timestamp, message) {
+		$(that.node).append(teamName + ": " + timestamp + message + "<br/>");
+	    });
+	});
+
+This simple widget illustrates several important points:
+
+* The base widget object (`this') has several baked-in properties and
+  methods that are available to individual widgets. These include
+  this.team (the team that this widget is a part of) and this.node
+  (the DOM element of the widget).
+
+* The team object (`this.team') also has baked-in properties and
+  methods. These include the queue function, which takes an event-name
+  as its argument. It's possible to subscribe to an event's queue
+  using this.team.queue("EVENT").subscribe. The argument is a function
+  which is called whenever the event is published. The arguments to
+  the function are different for different events.
+