Creating New Widgets

From KnowledgeTree Document Management Made Simple

New widgets should all derive from KTWidget in lib/forms/basewidget.inc.php. Depending on how simple or complex your widget is, you may need to override some or all of the inherited functions. The key ones are listed below, with all functions described at the end. Bear in mind that this covers the API of KTWidget - subclasses may have different APIs.

You will also want to read Widget Lifecycle.

Contents 1 Key Functions 2 Key Base Variables 3 Key Config Variables 4 All Functions 5 Registering your Widget

Key Functions

• configure ($aOptions) -> (PEAR::Error or null)
  • Takes an array of options which is used to configure the widget. This is one of the most important methods in the API, since it drives the usage of the widget. A few things to note:
    • $aOptions should always be passed to parent::configure($aOptions);.
    • configure can return a PEAR::raiseError. Use this to ensure that widget-users supply all required arguments. (e.g. name, etc.)
    • don't forget to check the parent::configure() for raised errors
  • It causes a number of useful values to be set on the object - see "Key Config Variables" for more info.
• getWidget () -> (HTML)
  • Returns the actual Widget HTML. This is then wrapped in the outer HTML (div class="field" etc., the label, etc.)
• process ($data) -> (array)
  • given the contents of the "data" array (where all data from the form is placed), return an array of $fieldname => $value to be added to the results set.
  • bear in mind that this should have a sane format which is compatible with both the "value" config options and the "setDefault" method.
  • $fieldname should be the basename.
• setDefault ($mValue) -> (null)
  • override the default value to be used. This is used to persist the old value during errors, so it is essential that it is handled
• getDefault () -> ($mValue)
  • get the current value of this widget (e.g. $this->value). Used before setting the default.

Key Base Variables

There are a few major variables which should be set on a class level.

• sNamespace: the namespace this will have. Used predominantly for documentation purposes (so users can find the widget that's instantiated by a particular call)
• sTemplate: the template to use in the getWidgets call. See Default Widget Template Parameters for more details.
• aJavascript: an array containing javascript references to add to $oPage.
• aCSS: Stylesheet references to add to $oPage.

Key Config Variables

These are the standard variables accepted by "basewidget". See subclasses for more info on what they do...

• $this->sLabel = $aOptions['label']
  • the label used to describe the widget
• $this->sDescription = $aOptions['description']
  • the description above the widget
• $aOptions['important_description']
  • a "important" description given in bold after the normal description. Use for important usage information which may be missed in a general description
• $this->sName = $this->sOrigname = $this->sBasename = $aOptions['name']
  • the internal "name" assigned to the object. These are actually slightly different due to the calling of wrapName (see below). What's important is:
    • form inputs should use the "name" value
    • processing, outputting, etc. should use "basename" which is the original base name.
• $this->value = $aOptions['value']
  • the initial value of the field. should look like the output of process() and the input of setDefault()
• $this->bRequired = ($aOptions['required'] == true)
  • whether this is a required field. combined with autovalidate, controls whether the required validator is automatically added to it.
• $this->sId = $aOptions['id']
  • the "id" that should be associated with this widget (in whatever form makes sense)
• $this->aOptions = $aOptions
  • the original options. useful to use this after parent::configure() has been called, in case the options array is manipulated somehow.
• $this->bAutoValidate = $aOptions['autovalidate']

All Functions

Largely speaking this is still a "use the source, luke" situation, but here's a brief overview.

• function configure($aOptions)
  • set up the initial configuration of the widget
• function getDefault()
  • get the current "active" value before rendering
• function setDefault($mValue)
  • set the active value before rendering
• function getBasename()
  • get the "base name" or "original name"
• function wrapName($sOuter)
  • wrap the basename in some outer namespace. Used to place all the data into the "data" array or further nested arrays (e.g. data[myfieldset][name]. Be *very* careful when overriding this.
• function setErrors($aErrors = null)
  • set the error array.
• function requireJSResource($sResourceURL)
  • analogous to $aJavascript
• function render()
  • outer render method - includes all wrapping. You usually don't want to override this unless you want none of the normal decorations.
• function getWidget()
  • inner render method. Returns the HTML that gets wrapped by render().
  • Takes a number of different parameters:
    • FIXME document the "normal" template params
• function getValidators()
  • returns a validator / array of validators for a widget that would be "expected". Currently used for "required".
• function process($raw_data)
  • extract from the $_REQUEST the values as they are useful. For example, a widget may have 8 select dropdowns to represent a single concept to the user, and the single (combined) value is the logical value for the field.

Registering your Widget