X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-developer.markdown;h=a6ca04bba4700924a105ad94d4bfd75aba9c6361;hb=9a18fee5262c0f2e21861574e29bc4f3f44ea687;hp=d302027c55d748d328f27b2aabcf861857e0001d;hpb=1d330de3056b4799c7cef1495ba98dd4faaa6154;p=mkws-moved-to-github.git diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown index d302027..a6ca04b 100644 --- a/doc/mkws-developer.markdown +++ b/doc/mkws-developer.markdown @@ -3,6 +3,29 @@ % 11 August 2014 +Required development tools +========================== + +If you are building the widget set, as opposed to just using it, 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`. + +To compile the default templates you'll need to install the stable +version of Handlebars. Currently it's at 2.0.0 and available by npm: + + $ npm install handlebars@2.0.0 -g + + Overview ======== @@ -134,6 +157,46 @@ be used by the derived widget. * `String this.value()` -- A function returning the value of the widget's HTML element. +* `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 +example, the `Builder` widget uses a `callback` property as the +function that it use to publish the widget definition that it +constructs. This defaults to the builtin function `alert`, but can be +overridden by derived widgets such as `ConsoleBuilder`. + Team methods ------------ @@ -148,9 +211,10 @@ properties. * `Num team.totalRecordCount()` * `Num team.currentPage();` * `String team.currentRecordId()` -* `String team.currentRecordData()` -- - Simple accessor functions that provide the ability to read - properties of the team. +* `String team.currentRecordData()` + +These are all simple accessor functions that provide the ability to +read properties of the team. * `Array team.filters()` -- Another accessor function, providing access to the array of @@ -160,13 +224,17 @@ properties. convenient to do it this way. If you must insist on using this, see the `Navi` widget, which is the only place it's used. +* `Bool team.targetFiltered(targetId)` -- + Indicates whether the specified target has been filtered by + selection as a facet. This is used only by the `Facet` widget, + and there is probably no reason for you to use it. + * `Hash team.config()` -- Access to the team's configuration settings. There is almost certainly no reason to use this: the settings that haven't been overridden are accessible via `this.config`. -* `Void team.set_sortOrder(string)` -* `Void team.set_perpage(number)` -- +* `Void team.set_sortOrder(string)`, `Void team.set_perpage(number)` -- "Setter" functions for the team's sortOrder and perpage functions. Unlikely to be needed outside of the `Sort` and `Perpage` widgets. @@ -175,10 +243,6 @@ properties. Returns the queue associated with the named event: this can be used to subscribe to the event (or more rarely to publish it). -* `Bool team.targetFiltered(targetId)` -- - Indicates whether the specified target has been filtered by - selection as a facet. - * `Void team.newSearch(query, sortOrder, maxrecs, perpage, limit, targets, targetfilter)` -- Starts a new search with the specified parameters. All but the query may be omitted, in which case the prevailing defaults @@ -208,6 +272,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.