X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-developer.markdown;h=9d3ac4b72ed7151ec5d85556e9f8d1a9cc0d5b70;hb=c209fd276576df2500e25299a00120db4c573884;hp=2689eb67de3f8334bb8c6568e3ee48eae6be3ad2;hpb=3271437c3795ec604b1aa8abdf3e052a072ff070;p=mkws-moved-to-github.git diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown index 2689eb6..9d3ac4b 100644 --- a/doc/mkws-developer.markdown +++ b/doc/mkws-developer.markdown @@ -1,13 +1,90 @@ % The MasterKey Widget Set developer's guide % Mike Taylor -% 11 August 2014 +% November 2014 -Overview +Introduction +============ + +This manual is for people who want to build the widget set from +source, develop the widget set's core code, or (more likely) create +their own widgets as extensions to the main set. + +Those who want to use existing widgets should read +[The MKWS manual: embedded metasearching with the MasterKey Widget +Set](mkws-manual.html) instead. + + +Required development tools +========================== + +If you are building the widget set, you will need the following Debian +packages (or their equivalents on your operating system): + + $ sudo apt-get install curl git make unzip apache2 \ + pandoc yui-compressor libbsd-resource-perl + +You also need Node.js, but unfortunately the `node-js` package is not +available for Debian wheezy. You can either get it from +wheezy-backports or download the source from +http://nodejs.org/download/ and build it yourself. You need both Node +itself and its package manager NPM: `make install` puts them into +`/usr/local/bin`. + + +Concepts ======== -Core concepts -------------- +Code structure +-------------- + +The code of the widget set is in four main layers, described here from +the bottom up: + +1. The core code, which manages the set of widget teams, default +options, authentication onto the Service Proxy, and the creation of +widgets from HTML elements. +This code is in `mkws-core.js` + +2. The team code, which manages teams of widgets. This is responsible +for the collections of widgets that make up teams, event queues, and +handling search-and-retrieval events +This code is in `mkws-team.js` + +3. The generic widget code, which handles the creation of widget +objects, parsing configuration attributes from their HTML elements, +and firing off automatic searches. + +4. The code for individual widgets, which is specific to those +widgets. It often involves subscribing to events and responding to +them by setting the HTML of the widget element, but need not do +so. The code for many of the most important widgets is in +`mkws-widget-main.js`, but certain other widgets are defined in other +files beginning with the prefix `mkws-widget-`. + +In addition to this code, there are several source files containing +support code: + +* `mkws-filter.js` contains support routine implementing the +filter-set data structure, which contains information about which +filters (e.g. by target, or by facet) are in force. + +* `mkws-handlebars.js` contains Handlebars helpers which can be used +by the HTML templates. + +* `mkws-popup.js` defines a special widget for creating popup + windows. These may, but need not, contain other MKWS widgets, + forming a popup searching application. + +The final component of the source code is the set of Handlebars +templates, in the `templates` directory, which are used to emit the +HTML of the various widgets' contents. These are compiled into the +file `mkws-templates.js`. + + + +Defining new types of widget +---------------------------- Development with MKWS consists primarily of defining new types of widgets. These can interact with the core functionality is several @@ -134,13 +211,38 @@ be used by the derived widget. * `String this.value()` -- A function returning the value of the widget's HTML element. -* TODO autosearch() - -* TODO hideWhenNarrow() - -* TODO subwidget() - -* TODO expandValue() +* `VOID autosearch()` -- + Registers that this kind of widget is one that requires an + automatic search to be run for it if an `autosearch` attribute + is provided on the HTML element. This is appropriate for + widgets such as `Records` and `Facet` that display some part + of a search result. + +* `VOID hideWhenNarrow()` -- + Registers that this widget should hide itself when the page + becomes "narrow" -- that is, fewer pixels in width that the + threshhold value specified by the top-level configuration item + `responsive_design_width`. Should be used for "unimportant" + widgets that can be omitted from the mobile version of a site. + +* `expandValue()` -- + TODO: either document this or remove it from the API. + +* `subwidget(type, overrides, defaults)` -- + Returns the HTML of a subwidget of the specified type, which + can then be inserted into the widget using the + `this.node.html` function. The subwidget is given the same + attributes at the parent widget that invokes this function, + except where overrides are passed in. If defaults are also + provided, then these are used when the parent widget provides + no values. Both the `overrides` and `defaults` arguments are + hashes: the latter is optional. + + See for example the `Credo` widget defined in the example + area's `mkws-widget-credo.js` file. This uses several + invocations of `subwidget` to create a complex compound widget + with numerous text, facet and image panes. TODO: rename this + widget and everything related to it. In addition to these properties and methods of the bare widget object, some kinds of specific widget add other properties of their own. For @@ -224,6 +326,13 @@ infelicities reflect the fact that some code that rightly belongs in widgets is still in the team. When we finish migrating it, the widget API should get simpler. + +Events +------ + +TODO: list of events that can be usefully subscribed to. + + - - - -Copyright (C) 2013-2014 by IndexData ApS, +Copyright (C) 2013-2014 Index Data ApS.