Form JavaScript and validation
ImpressPages automatically adds jQuery Tools validation script to all forms generated using \Ip\Form object. Use addValidator() method to add required validation rules when creating form object in PHP.
This is what ImpressPages does automatically for you from a JavaScript side:
- marks incorrect fields and prevents form submission till all fields are correct,
- if all fields are correctly filled in, submits form using AJAX expecting JSON response,
- if a form submission response contains errors attribute with associative array of errors, those errors are displayed,
- if a form submission response has a redirectUrl attribute, user will be redirected to that URL.
- if a form submission response has a replaceHtml attribute, form's HTML will be replaced with returned HTML.
- if a form submission response has an alert attribute, browser will show an alert (since 4.2.0)
ImpressPages listens to the default JavaScript submit event and executes AJAX request instead of standard form submit. On AJAX response ipSubmitResponse event is triggered with event information as first parameter and response data from PHP as a second parameter. If you want to do some actions in JavaScript after a form has been submitted, listen to ipSubmitResponse event instead of original form submit event.
Add a hidden field with one of these names aa, sa, pa to set the controller that handles form submission and learn how to validate user's data and supply JSON answer in PHP.
Example that catches ipSubmitResponse event after form submit via AJAX:
$('someFormSelector').on('ipSubmitResponse', function(e, response) {
if (response.errors) {
//do something if there are some errors
} else {
//do something if there are no errors
}
});
JavaScript form validation is nice thing to have, but it is not enough, as form data should be validated also on a server before processing. You should not rely on JavaScript validations, as they can be easily bypassed by advanced user. PHP validation is always mandatory!
Validation is activated only on those forms that are present on onReady event. If you add a new form to a page dynamically, execute ipInitForms() function to initialize JavaScript validation manually.
Not all validators have JavaScript validation implemented. But that's not a big issue, as fields will still be validated in PHP side and shown correctly for the user after submit.
Disable JavaScript
You can disable automatic form submission / error checking by setting AJAX setting to false while generating a form object.
$form->setAjaxSubmit(false)
ipInitForms() metehod
This method initializes all that JavaScript functionality described above. Additionally it triggers ipInitForms JavaScript event. If you implement your own custom form field that has JavaScript involved, catch this event and do initialization on your field type.
$(document).on('ipInitForms', function(){
//do your stuff
});