Understanding the Form Process Flow

First of all, don't adjust your screen. =)

The "form*** called" messages you see are showing up to illustrate how the Form process flow works. While you don't necessarily need to know all the details of the form engine, it can be helpful to have some knowledge when you are debugging problems with your form.

As we mentioned earlier, Form objects are stateful, with the state persisting through all the user interactions (e.g. ServerActions, etc.). But the Form objects are also event-driven. This is why we state that Forms are a "stateful, event-driven architecture for web-based forms."

To make this all work, QCubed outputs HTML Form objects so that their actions "post-back" to themselves. In other words, they submit all the form data to the same page the form is on. Similarly, all ajax calls also call the same page they are on. On every execution of a Form, the following actions happen:

1. The form object will determine if we are:
   • Loading the page for the first time, or
   • Loading the page after a form has submitted itself back to itself (called a post-back), or
   • Loading the page as a result of a form submitting an Ajax call back to itself.
2. If it is a post-back or ajax call from a previously loaded form, then it will retrieve the form's state from the FormState in order to reconstruct the entire form object in its previous state from before the submit was processed. It will then go through all the controls and update their values according to the user-entered data submitted via the HTML Post or Ajax call.
3. Next, the formRun() method will be triggered. This will be run regardless if we're viewing the page fresh or if we've re-posted back to the page. formRun() is a good place to put code that you need to run every time a form is loaded, like code that verifies that the user has permission to view the page.
4. Next, if we are viewing the page fresh (e.g. not via a post back), the formCreate() method (if defined) will be run. formCreate() is typically where you would define and instantiate your various Form controls. Otherwise, the formLoad() method will be run.
5. Next, if we're posted back because of a Server or Ajax action that points to a specific PHP method, the following will happen:
   • First, if the control that triggered the event has its CausesValidation property set, then the form will go through validation. The form will call validate() on the relevent controls, and then it will call formValidate on itself. More information on validation can be seen in the upcoming Calculator examples.
   • Next, if validation runs successfully or if no validation is requested (because CausesValidation was set to false), then the PHP method that the action points to will be run. This is the typical way that QCubed responds to things like button clicks.
   So in this repeat of the "Hello World" example, when you click on btnButton, the btnButton_Click method will be executed during this step.
6. The formPreRender() method will then be run.
7. The HTML include template file is included (to render out the HTML).
8. And finally, the formExit() is run after the HTML has been completely outputted.

So, a Form can have any combination of the five following methods defined to help customize Form and Control processing:

• formRun()
• formLoad()
• formCreate()
• formValidate()
• formPreRender()
• formExit()

All are optional, and to intercept any of them, simply implement that method in your Form class.

Click the button to change my message.

Click Me!