doc/mkws-developer.txt

   1 Development with MKWS consists primarily of defining new types of
   2 widgets. These can interact with the core functionality is several
   3 defined ways.
   4
   5 You cleare a new widget ttpe this by calling the
   6 mkws.registerWidgetType function, passing in the widget name and a
   7 function. The name is used to recognise HTML elements as being widgets
   8 of this type -- for example, if you register a "Foo" widget, elements
   9 like <div class="mkwsFoo"> will be widgets of this type.
  10
  11 The function promotes a bare widget object (passed as `this') into a
  12 widget of the appropriate type. MKWS doesn't use classes or explicit
  13 prototypes: it just makes objects that have the necessary
  14 behaviours. Widgets have *no* behaviours that they have to provide:
  15 you can make a doesn't-do-anything-at-all widget if you like:
  16
  17         mkws.registerWidgetType('Sluggard', function() {});
  18
  19 More commonly, widgets will subscribe to one or more events, so that
  20 they're notified when something interesting happens. For example, the
  21 "Log" widget asks to be notified when a "log" event happens, and
  22 appends the logged message to its node, as follows:
  23
  24         mkws.registerWidgetType('Log', function() {
  25             var that = this;
  26
  27             this.team.queue("log").subscribe(function(teamName, timestamp, message) {
  28                 $(that.node).append(teamName + ": " + timestamp + message + "<br/>");
  29             });
  30         });
  31
  32 This simple widget illustrates several important points:
  33
  34 * The base widget object (`this') has several baked-in properties and
  35   methods that are available to individual widgets. These include
  36   this.team (the team that this widget is a part of) and this.node
  37   (the DOM element of the widget).
  38
  39 * The team object (`this.team') also has baked-in properties and
  40   methods. These include the queue function, which takes an event-name
  41   as its argument. It's possible to subscribe to an event's queue
  42   using this.team.queue("EVENT").subscribe. The argument is a function
  43   which is called whenever the event is published. The arguments to
  44   the function are different for different events.
  45