doc/mkws-developer.markdown

   1 % The MasterKey Widget Set developer's guide
   2 % Mike Taylor
   3 % 11 August 2014
   4
   5
   6 Introduction
   7 ============
   8
   9 Development with MKWS consists primarily of defining new types of
  10 widgets. These can interact with the core functionality is several
  11 defined ways.
  12
  13 You create a new widget type by calling the mkws.registerWidgetType
  14 function, passing in the widget name and a function. The name is used
  15 to recognise HTML elements as being widgets of this type -- for
  16 example, if you register a "Foo" widget, elements like <div
  17 class="mkwsFoo"> will be widgets of this type.
  18
  19 The function promotes a bare widget object (passed as `this') into a
  20 widget of the appropriate type. MKWS doesn't use classes or explicit
  21 prototypes: it just makes objects that have the necessary
  22 behaviours. Widgets have *no* behaviours that they have to provide:
  23 you can make a doesn't-do-anything-at-all widget if you like:
  24
  25         mkws.registerWidgetType('Sluggard', function() {});
  26
  27 More commonly, widgets will subscribe to one or more events, so that
  28 they're notified when something interesting happens. For example, the
  29 "Log" widget asks to be notified when a "log" event happens, and
  30 appends the logged message to its node, as follows:
  31
  32         mkws.registerWidgetType('Log', function() {
  33             var that = this;
  34
  35             this.team.queue("log").subscribe(function(teamName, timestamp, message) {
  36                 $(that.node).append(teamName + ": " + timestamp + message + "<br/>");
  37             });
  38         });
  39
  40 This simple widget illustrates several important points:
  41
  42 * The base widget object (`this') has several baked-in properties and
  43   methods that are available to individual widgets. These include
  44   this.team (the team that this widget is a part of) and this.node
  45   (the DOM element of the widget).
  46
  47 * The team object (`this.team') also has baked-in properties and
  48   methods. These include the queue function, which takes an event-name
  49   as its argument. It's possible to subscribe to an event's queue
  50   using this.team.queue("EVENT").subscribe. The argument is a function
  51   which is called whenever the event is published. The arguments to
  52   the function are different for different events.
  53
  54 * The value of `this' is lost inside the subscribe callback, so it
  55   must be saved if it's to be used inside that callback (typically as
  56   a local variable named `that').
  57
  58
  59 Specialisation (Inheritance)
  60 ============================
  61
  62 Many widgets are simple specialisations of existing widgets. For
  63 example, the "Record" widget is the same as the "Records" widget
  64 except that it defaults to displaying a single record. It's defined as
  65 follows:
  66
  67         mkws.registerWidgetType('Record', function() {
  68             mkws.promotionFunction('Records').call(this);
  69             if (!this.config.maxrecs) this.config.maxrecs = 1;
  70         });
  71
  72 Remember that when a promotion function is called, it's passed a base
  73 widget object that's not specialised for any particular task. To make
  74 a specialised widget, first promote that base widget into the type
  75 that you want to specialise from -- in this case, "Records" -- using
  76 the promotion function that's been registered for that type.
  77
  78 Once this has been done, the specialisations can be introduced. In
  79 this case, it's a very simple matter of changing the "maxrecs"
  80 configuration setting to 1 unless it's already been given an explicit
  81 value. (That would occur if the HTML used an element like <div
  82 class="mkwsRecord" maxrecs="2">, though it's not obvious why anyone
  83 would do that.)
  84
  85
  86 Widget Properties and Methods
  87 =============================
  88
  89 String this.type
  90         A string containing the type of the widget.
  91
  92 Team this.team
  93         The team object to which this widget belongs. The team has
  94         several additional important properties and methods, described
  95         below.
  96
  97 DOMElement this.node
  98         The DOM element of the widget
  99
 100 Hash this.config
 101         A table of configuration values for the widget. This table
 102         inherits missing values from the team's configuration, which
 103         in turn inherits from the top-level MKWS configuration, which
 104         inherits from the default configuration. Instances of widgets
 105         in HTML can set configuration items as HTML attributes, as in
 106         <div class="mkwsRecords" maxrecs="2">.
 107
 108 String this.toString()
 109         A function returning a string that briefly names this
 110         widget. Can be useful in logging.
 111
 112 Void this.log(string)
 113         A function to log a string for debugging purposes. The string
 114         is written on the browser console, and also published to any
 115         "log" subcribers.
 116
 117 String this.value()
 118         A function returning the value of the widget's HTML element.
 119
 120
 121 Team methods
 122 ============
 123
 124 Since the team object is supposed to be opaque to widgets, all access
 125 is via the following API methods rather than direct access to
 126 properties.
 127
 128 String team.name()
 129 Bool team.submitted()
 130 Num team.perpage()
 131 Num team.totalRecordCount()
 132 Num team.currentPage();
 133 String team.currentRecordId()
 134 String team.currentRecordData()
 135         Simple accessor functions that provide the ability to read
 136         properties of the team.
 137
 138 Array team.filters()
 139         Another accessor function, providing access to the array of
 140         prevailing filters (which narrow the search results by means
 141         of Pazpar2 filters and limits). This is really too complicated
 142         an object for the widgets to be given access to, but it's
 143         convenient to do it this way. See the "Navi" widget, which is
 144         the only place it's used.
 145
 146 Hash team.config()
 147         Access to the team's configuration settings. There is almost
 148         certainly no reason to use this: the settings that haven't
 149         been overridden are accessible via this.config.
 150
 151 Void team.set_sortOrder(string)
 152 Void team.set_perpage(number)
 153         "Setter" functions for the team's sortOrder and perpage
 154         functions. Unlikely to be needed outside of the "Sort" and
 155         "Perpage" widgets.
 156
 157 Queue team.queue(eventName)
 158         Returns the queue associated with the named event: this can be
 159         used to subscribe to the event (or more rarely to publish it).
 160
 161 Bool team.targetFiltered(targetId)
 162         Indicates whether the specified target has been filtered by
 163         selection as a facet.
 164
 165 Void team.newSearch(query, sortOrder, maxrecs, perpage, limit, targets, targetfilter)
 166         Starts a new search with the specified parameters. All but the
 167         query may be omitted, in which case the prevailing defaults
 168         are used.
 169
 170 Void team.reShow()
 171         Using the existing search, re-shows the result records after a
 172         change in sort-order, per-page count, etc.
 173
 174 String team.recordElementId(recordId)
 175         Utility function for converting a record identifer (returned
 176         from Pazpar2) into a version suitable for use as an HTML
 177         element ID.
 178
 179 String team.renderDetails(recordData)
 180         Utility function returns an HTML rendering of the record
 181         represented by the specified data.
 182
 183 Template team.loadTemplate(templateName)
 184         Loads (or retrieves from cache) the named Handlebars template,
 185         and returns it in a form that can be invoked as a function,
 186         passed a data-set.
 187
 188 Some of these methods either (A) are really too low-level and should
 189 not be exposed, or (B) should be widget-level methods. The present
 190 infelicities reflect the fact that some code that rightly belongs in
 191 widgets is still in the team. When we finish migrating it, the widget
 192 API should get simpler.
 193