Widget Lifecycle

From KnowledgeTree Document Management Made Simple

All widgets and validators go through a defined lifecycle as part of a form. This lifecycle can span multiple requests, and occur in different places within the system. It is important that widget developers understand most of this, so that their contributions can behave like other widgets as far as possible.

You may also want to review the "Creating New Widgets" guide.

1. Creation: The widget is created via a factory call on the form. The Widget object is instantiated, and the "configure($aOptions)" method is called with the parameters passed through.
2. The form is rendered. This triggers a series of actions:
   1. the forms code checks to see if there is old request data available for this form so that it can identify any errors or default values.
   2. for each widget the form calls
      1. $widget->wrapName('data') - this causes the "name" variable on a widget to change. Essentially, it is saying "when you return information about this widget from the form, please make sure it is in the following array". So, if you had a widget with a name of "var1", wrapName('data') would be telling the widget to use the name "data[var1]" as the HTML input's "name" attribute. Note: the original value of the "name" attribute is still available as the "basename" attribute.
      2. $widget->setdefault($default) - this uses either the widget's current default (if no old value is available) or the output that $widget->process($data) gave during the previous request (e.g. before validation)
      3. $widget->setErrors($errors) for any errors that were generated during a previous run
   3. the widget is rendered. To do so, the system calls $widget->render()
      1. which calls $widget->getWidget(). This includes a number of different inputs (var1 and var2) which the template refers to as "{$name}[var1]" and "{$name}[var2]"
   4. all the widgets are output to the user.
3. the form is validated
   1. the widget's "process($data)" method is called with the contents of $_REQUEST['data']. This is an array, and the widget should be able to get the value of any inputs it had in it. If it used the "name" variable correctly, these will be something like $data[$basename]['var1'] and $data[$basename]['var2']. These values should be processed into the same format as the widgets "value" parameter
   2. the widget's getValidators() method is called, to get a list of mandatory validators
   3. these are then run.
   4. the output of process($data) is stored internally, in case the form validation failed.
   5. all of this returns an array of "results" => array(), "errors" => array()
4. the calling dispatcher / code checks the validation, performs any additional validation, and the either (a) calls the form's handleError() method or (b) processes the data and moves on. handleError causes the user to be bounced back to the "fail_action" set on the form.