doc/mkws-developer.txt

   1 INTRODUCTION
   2 ============
   3
   4 Development with MKWS consists primarily of defining new types of
   5 widgets. These can interact with the core functionality is several
   6 defined ways.
   7
   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.
  13
  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:
  19
  20         mkws.registerWidgetType('Sluggard', function() {});
  21
  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:
  26
  27         mkws.registerWidgetType('Log', function() {
  28             var that = this;
  29
  30             this.team.queue("log").subscribe(function(teamName, timestamp, message) {
  31                 $(that.node).append(teamName + ": " + timestamp + message + "<br/>");
  32             });
  33         });
  34
  35 This simple widget illustrates several important points:
  36
  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).
  41
  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.
  48
  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').
  52
  53
  54 SPECIALISATION (INHERITANCE)
  55 ============================
  56
  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
  60 follows:
  61
  62         mkws.registerWidgetType('Record', function() {
  63             mkws.promotionFunction('Records').call(this);
  64             if (!this.config.maxrecs) this.config.maxrecs = 1;
  65         });
  66
  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.
  72
  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.)
  78
  79
  80 WIDGET PROPERTIES AND METHODS
  81 =============================
  82
  83 this.type -- a string containing the type of the widget.
  84
  85 this.team -- the team object to which this widget belongs. The team
  86         has several additional important properties and methods,
  87         described below.
  88
  89 this.node -- the DOM element of the widget
  90
  91 this.config -- a table of configuration values for the widget. This
  92         table inherits missing values from the team's configuration,
  93         which in turn inherits from the top-level MKWS configuration,
  94         which inherits from the default configuration. Instances of
  95         widgets in HTML can set configuration items as HTML
  96         attributes, as in <div class="mkwsRecords" maxrecs="2">.
  97
  98 this.toString() -- a function returning a string that briefly names
  99         this widget. Can be useful in logging.
 100
 101 this.log(string) -- a function to log a string for debugging
 102         purposes. The string is written on the browser console, and
 103         also published to any "log" subcribers.
 104
 105
 106 TEAM PROPERTIES AND METHODS
 107 ===========================
 108
 109 team.queue
 110 team.name
 111 team.targetFiltered(data[i].id)
 112 team.config()
 113 team.log()
 114 team.newSearch(query, sortOrder, maxrecs, perpage, limit, targets, targetfilter);
 115 team.totalRecordCount()
 116 team.perpage()
 117 team.currentPage();
 118 team.recordElementId(hit.recid[0])
 119 team.currentRecordId()
 120 team.currentRecordData()
 121 team.renderDetails()
 122 team.loadTemplate()
 123 team.filters()
 124 team.set_sortOrder()
 125 team.submitted()
 126 team.resetPage()
 127 team.reShow()
 128 team.set_perpage()