CiviCRM Architecture - CiviCRM Forms and Wizards

2006-11-14 06:54
Written by

CiviCRM Forms and Wizards (multi-page forms) are based on PEAR's HTML_QuickForm_Controller. (QFC). QFC in turn is based on HTML_QuickForm (QF). It was easier for us to model a single form as a one page wizard, and hence all CiviCRM forms are instances of QFC

The basic Form object is CRM_Core_Form. All forms are derived from this class. Each derived class is expected to implement the following functions

  • function preProcess( ): This function is called before a form is built. All objects needed to build the form should be built in this function.
  • function buildQuickForm( ): This function builds the form. There are some helper functions in CRM_Core_Form to build some elements (Radio, Select, Yes/No etc). Classes typically call a mixture of these helper functions and QF functions directly
  • function setDefaultValues( ): Default values when the form is first rendered. Typically we use the same form to create and edit a database record. An object being edited has database values retrieved from the db and displayed to the user
  • function addRules( ): Add local and global rules to the form. Forms typically have different types of rules. The first class are simple rules (value is required, value an integer / money / email etc). The second class are data dependent rules (same name does not exist in database, min value greater than a database specified minimum etc). The third class are rules that match multiple field values (first name and last name or email is required, the state specified does not belong to the specified country)
  • function postProcess( ): This function is called after the form has been "POST"'ed and validated.

When a form F is first rendered, the functions called are:

preProcess -> buildQuickForm -> setDefaultValues -> addRules -> display

When the user submits the same form F, the functions called are:

preProcess -> buildQuickForm -> setDefaultValues -> addRules -> validate

If the form is validated (i.e. it passes all the sets of rules described above) then postProcess is called else the form is displayed with the errors returned from validation (drupal developers will notice the similarity between the above sequence and FAPI 2.0)

If there are two forms in your wizard F1 and F2 the following functions are called when form F1 is submitted

F1: preProcess -> buildQuickForm -> setDefaultValues -> addRules -> validate -> postProcess

F2: preProcess -> buildQuickForm -> setDefaultValues -> addRules

Filed under