CiviCRM Architecture - CiviCRM Forms and Wizards

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

Comments

I am grasping this info to *some* (small) extent. In looking at CRM_Core_Form, I am confused by this idea of virtual functions. Is there a file in the tree somewhere that I can see an object being built in the preProcess function? Or am I just lost?

will help you quite a bit. We use a lot of virtual functions throughout the system to customize stuff if needed. Dont know any good reference offhand, but i suspect a web search will give u enuf reading

lobo

I think it's worth reminding everyone to also check out the excellent post on the templating system - I just got quite confused about form elements not displaying until I realised I needed a template corresponding to my new form to get it to display - which is obvious if you've recently read the templating post, but not so obvious otherwise.