Handling Form Submit
Form class is used for both rendering and submit data fetching. There are 4 steps to form cycle
- Initialize form
- Load default data
- If form submitted, it's handled
- Form is rendered
- Initialization. $f=$p->add(); is called, template is loaded and form->init() is automatically executed. Inside init() form's tempalte is separated into chunks.
- Field are inserted into forms with addField();
- Optionally isSubmitted() is called.
- loadData() is called. It's used when form is linked with database for data loading.
- submitted() is called. Verifies if form was really submitted.
- It calls loadPOST() for all fields recurrsively
- Calls validate() recursively. Any errors are accumulated in $f-<errors
- submitted() returns true if didn't receive any validation errors
- isSubmitted() returns true if data was submitted and contained no errors
- Before rendering — if isSubmitted() wasn't used then submitted() method of respective form is called then
- Execution is expected to be terminated when form submission is handled. If it wasn't done until rendering, lateSubmit() is called which output console warning about missing form handler.
- Global rendering starts which recursively renders fields first, then form
Dynamically Submitted Forms
When form is added to the page, it's being a normal page with action and using POST for submitting. However form automatically initialise form widget. This widget (file ui.atk4_form.js) is based on jQuery UI Widget Factory. It does not provide any visual enhancement for the form, however is designed to improve submission as well as add some additional features to the form.
Form's submit event is redefined to use $('#form').atk4_form('submitForm'); method instead. This method collect field values, encodes them and sends using AJAX request using $.atk4.get()
It is worth noting that instead of using $.ajax, form uses $.atk4.get(), which introduces number of improvements (timeout checking, on-js-loaded handler, tracking number of files being loaded, support for object-based URLs) but also relies on $.ajax. For more information on AJAX functions, see AJAX documentation of Agile Toolkit
If for some reason jQuery UI form enhancement component wasn't loaded, then form is being sent through POST like a normal form.
Using isSubmitted function
Use of this function is really simple. It returns true if form was submitted. If you are new to forms in Agile Toolkit, you must remember that Form and Page will be initialized twice. First time when form was rendered, second time when it is submitted. Therefore isSubmitted() must be always placed after form is fully initialized.
Typical use would put isSubmitted() into the if block. This construction is used often, so you might want to place it into the snippet inside your IDE / Editor
Agile Toolkit 4.1 plans to introduce new way for form submission checking. It will be done through function onSubmit(callaback) which is specifically designed to be used with closures.
Both methods are essentially doing the same thing. isSubmitted() have been used in older versions of PHP, where closures were not easy to create.
however with closures you can now create a function call-back like this:
One significant change though is that onSubmit() will capture some exceptions and will automatically display them on the form. Therefore if your model has this
throw $this->exception('Wrong data','ForUser')->setField('name');
Then "name" field will be highlighted with this error.
If you are defining your own form, you may want to re-define submitted() function. This approach offers no major benefits over isSubmitted approach, but is preserved for historical reasons.