4 Development with MKWS consists primarily of defining new types of
5 widgets. These can interact with the core functionality is several
8 You create a new widget type by calling the mkws.registerWidgetType
9 function, passing in the widget name and a function. The name is used
10 to recognise HTML elements as being widgets of this type -- for
11 example, if you register a "Foo" widget, elements like <div
12 class="mkwsFoo"> will be widgets of this type.
14 The function promotes a bare widget object (passed as `this') into a
15 widget of the appropriate type. MKWS doesn't use classes or explicit
16 prototypes: it just makes objects that have the necessary
17 behaviours. Widgets have *no* behaviours that they have to provide:
18 you can make a doesn't-do-anything-at-all widget if you like:
20 mkws.registerWidgetType('Sluggard', function() {});
22 More commonly, widgets will subscribe to one or more events, so that
23 they're notified when something interesting happens. For example, the
24 "Log" widget asks to be notified when a "log" event happens, and
25 appends the logged message to its node, as follows:
27 mkws.registerWidgetType('Log', function() {
30 this.team.queue("log").subscribe(function(teamName, timestamp, message) {
31 $(that.node).append(teamName + ": " + timestamp + message + "<br/>");
35 This simple widget illustrates several important points:
37 * The base widget object (`this') has several baked-in properties and
38 methods that are available to individual widgets. These include
39 this.team (the team that this widget is a part of) and this.node
40 (the DOM element of the widget).
42 * The team object (`this.team') also has baked-in properties and
43 methods. These include the queue function, which takes an event-name
44 as its argument. It's possible to subscribe to an event's queue
45 using this.team.queue("EVENT").subscribe. The argument is a function
46 which is called whenever the event is published. The arguments to
47 the function are different for different events.
49 * The value of `this' is lost inside the subscribe callback, so it
50 must be saved if it's to be used inside that callback (typically as
51 a local variable named `that').
54 SPECIALISATION (INHERITANCE)
55 ============================
57 Many widgets are simple specialisations of existing widgets. For
58 example, the "Record" widget is the same as the "Records" widget
59 except that it defaults to displaying a single record. It's defined as
62 mkws.registerWidgetType('Record', function() {
63 mkws.promotionFunction('Records').call(this);
64 if (!this.config.maxrecs) this.config.maxrecs = 1;
67 Remember that when a promotion function is called, it's passed a base
68 widget object that's not specialised for any particular task. To make
69 a specialised widget, first promote that base widget into the type
70 that you want to specialise from -- in this case, "Records" -- using
71 the promotion function that's been registered for that type.
73 Once this has been done, the specialisations can be introduced. In
74 this case, it's a very matter of changing the "maxrecs" configuration
75 setting to 1 unless it's already been given an explicit value. (That
76 would occur if the HTML used an element like <div class="mkwsRecord"
77 maxrecs="2">, though it's not obvious why anyone would do that.