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:
- 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.
- 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.
- 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.
- 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
- Next, if we're posted back because of a Server or Ajax action that points to a
specific PHP method, the following will happen:
So in this repeat of the "Hello World" example, when you click on btnButton, the btnButton_Click method
will be executed during this step.
- 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.
- The formPreRender() method will then be run.
- The HTML include template file is included (to render out the HTML).
- 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:
All are optional, and to intercept any of them, simply implement that method in your Form class.