X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-developer.markdown;h=a299eeb79bd28cee3891093c52af189dbf6b62c0;hb=461e26cfa97d511db70fafb89c889dbb089ac7b2;hp=ffa831bce1bbc5882d4614bd8b428a3e6288beed;hpb=f15742ce1adcc967c50fb03b71bad68a55628c63;p=mkws-moved-to-github.git diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown index ffa831b..a299eeb 100644 --- a/doc/mkws-developer.markdown +++ b/doc/mkws-developer.markdown @@ -145,13 +145,13 @@ Widget specialisation (inheritance) ----------------------------------- Many widgets are simple specialisations of existing widgets. For -example, the `Record` widget is the same as the `Records` widget -except that it defaults to displaying a single record. It's defined as -follows: +example, the `images` widget is the same as the `records` widget +except that it defaults to using the `images` template for displaying +its result list. It's defined as follows: - mkws.registerWidgetType('Record', function() { - mkws.promotionFunction('Records').call(this); - if (!this.config.maxrecs) this.config.maxrecs = 1; + mkws.registerWidgetType('images', function() { + mkws.promotionFunction('records').call(this); + if (!this.config.template) this.config.template = 'images'; }); Remember that when a promotion function is called, it's passed a base @@ -161,11 +161,11 @@ that you want to specialise from -- in this case, `Records` -- using the promotion function that's been registered for that type. Once this has been done, the specialisations can be introduced. In -this case, it's a very simple matter of changing the `maxrecs` -configuration setting to 1 unless it's already been given an explicit -value. (That would occur if the HTML used an element like `
`, though it's not obvious why anyone -would do that.) +this case, it's a very simple matter of changing the `template` +configuration setting to `'images'` unless it's already been given an +explicit value. (That would occur if the HTML used an element like +`
` to use a customised +template. Reference Guide @@ -180,7 +180,8 @@ that is passed into `registerWidgetType`'s callback function, and can be used by the derived widget. * `String this.type` -- - A string containing the type of the widget. + A string containing the type of the widget (`search`, + `switch`, etc.) * `Team this.team` -- The team object to which this widget belongs. The team has @@ -188,7 +189,8 @@ be used by the derived widget. below. * `DOMElement this.node` -- - The DOM element of the widget + The DOM element of the widget. Most often used for inserting + HTML into the widget element. * `Hash this.config` -- A table of configuration values for the widget. This table @@ -197,7 +199,7 @@ be used by the derived widget. inherits from the default configuration. Instances of widgets in HTML can set configuration items as HTML attributes: for example, the HTML element - `
`. + `
` creates a widget for which `this.config.maxrecs` is set to 10. * `String this.toString()` -- @@ -219,16 +221,6 @@ be used by the derived widget. 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 @@ -237,20 +229,15 @@ be used by the derived widget. 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. + hashes: the latter is optional. This can be used to assemble + compound widgets containing several subwidgets. 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 +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`. +overridden by derived widgets such as `console-builder`. Team methods @@ -331,7 +318,7 @@ API should get simpler. Events ------ -TODO: list of events that can be usefully subscribed to. +FIXME: list of events that can be usefully subscribed to. - - -