mForm Documentation
This class makes submitting your forms, especially your ajax forms, nicer and easier.
Setup
Create an instance of mForm.Submit and optionally set your options and events:
new mForm.Submit({ form: 'my_form' // The form the functions should be attached to // Here are your options and events, see below for more info });
Use ajax
The Option ajax is set to true by default, meaning your form will make an ajax call when submitted.
You can set it to false to disable ajax:
new mForm.Submit({ form: 'my_form', ajax: false });
Validation
Validation works the same way as with mForm.Core, only that validation happens onSubmit and not onBlur.
Remember that elements with the attribute data-required will also get validated:
options { validateOnSubmit: true, // Set to false to disable validation onSubmit blinkErrors: true, // When validation failed, the error-elements will blink shakeSubmitButton: true // The submit button will shake when validation failed }
<input … type="text" data-required> <input … type="text" data-validate="email"> <input … type="text" data-validate="min:6" data-required> <input … type="text" data-validate="max:12">
You can also set validateOnBlur to true in your mForm.Submit instance to also use validation onBlur for the elements of this form only.
Sometimes you might want to show an error hint to specific elements:
var myMForm = new mForm.Submit({ form: 'my_form' }); myMForm.showErrors([$('element_1'), $('element_2')]); myMForm.showErrors([$('element_1'), $('element_2')], true); // Also bounce the submit button
Events
In addition to the MooTools/Request events, you can also set following events to mForm.Submit:
onResponseSuccess | Fires when the response value is equal to option responseSuccess |
onResponseError | Fires when the response value is equal to option responseError |
onShowError | Fires when an validation error has been found |
new mForm.Submit({ form: 'my_form', responseError: 0, // onResponseError will fire when response == 0 responseSuccess: 1, // onResponseSuccess will fire when response == 1 onResponseSuccess: function(response) { alert('Request is successful: ' + response); }, onResponseError: function(response) { alert('Request is not successful: ' + response); }, onShowError: function(elements) { alert('Following elements didn\'t validate: ' + elements); } });
You can set the value any for responseSuccess or responseError. E.g. setting any for responseSuccess means, any response value which is not equal to responseError will fire onResponseError.
CAPTCHA
Your form can automatically send a CAPTCHA value in a hidden textfield.
The CAPTCHA value will only be sent if you actually interact with a form element, e.g. focus a textfield, select a checkbox etc.
new mForm.Submit({ form: 'my_form', captcha: 'This is my CAPTCHA value' // This value will be sent once a user interacted with the form });
This CAPTCHA solution is not as secure as commonly used ones like reCAPTCHA, Secureimage or similar libraries, but i've been using this one on many projects and haven't had a bot submitting my forms yet.
I recommend using the CAPTCHA option together with your browsers session:
<?php session_start(); $_SESSION('captcha') = md5(time() . rand(0, 10000)); // CAPTCHA: 9d3f5720c4db442ed4535a9000afae70 ?>
new mForm.Submit({ form: 'my_form', captcha: '<?php echo $_SESSION('captcha'); ?>' });
In above example, following hidden field will be added to your form once a user interacts with it:
<input type="hidden" name="captcha" value="9d3f5720c4db442ed4535a9000afae70">
Now you can check with php, if the CAPTCHA has been added and equals the one in your session:
<?php if($_POST['captcha'] == $_SESSION['captcha']) return true; else return false; ?>
To make your forms even more bot-secure, you can set the option timer:
timer: 5000
Then the form can only be submitted after 5 seconds, once mForm.Submit is initialized.
Options
This is the complete list of options you can set for mForm.Submit:
form: null, |
The element id or element reference of the form to use. |
ajax: true, |
Make an ajax request. In addition to the MooTools/Request events, you can set the following: onResponseSuccess: function(response) {} onResponseError: function(response) {} onShowError: function(elements) {} |
disableFormOnSubmit: true, |
All buttons of the form will be disabled when submitted. |
disableButtons: null, |
Additional buttons to disable when the form is submitted. |
addOverlay: true, |
Adds a overlay to the document when submitting the form, to prevent any clicks. |
showLoader: true, |
Adds a loading spinner to the submit button. |
captcha: '', |
This value will be sent in a hidden field only when the user made any action in the form. |
timer: 0, |
Another anti-bot option: If you set this to e.g. 5000, the form will only be ably to be submitted five seconds after mForm.Submit is initialised. |
submitButton: null, |
The button which shows the loading spinner (defaults to last submit button of the form). |
validateOnBlur: false, |
Set to true will validate elements of this form when they loose focus (onBlur event). |
validateOnSubmit: true, |
Validates the form elements when the form is submitted. |
blinkErrors: true, |
When validation fails, the error-elements will blink. |
shakeSubmitButton: true, |
When validation fails, submitButton will shake. |
responseError: 0, |
If the response value from the ajax call is 0, onResponseError will be fired. Set to 'any', onResponseError will be fired if the response value is not equal to responseSuccess. |
responseSuccess: 1 |
If the response value from the ajax call is 1, onResponseSuccess will be fired. Set to 'any', onResponseSuccess will be fired if the response value is not equal to responseError. |