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
}
 
<inputtype="text" data-required>
<inputtype="text" data-validate="email">
<inputtype="text" data-validate="min:6" data-required>
<inputtype="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:

onResponseSuccessFires when the response value is equal to option responseSuccess
onResponseErrorFires when the response value is equal to option responseError
onShowErrorFires 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.