This site contains the document for old version. Please upgrade to the latest version v1.0.0

reCaptcha2 add-on

Add and validate Google reCAPTCHA v2

← Add-ons

This add-on adds and validates Google reCAPTCHA v2 element.

If you still want to use Google reCAPTCHA v1, you can use the recaptcha1 add-on

Follow these steps to use this add-on:

Registering keys

You need to register a site and secret keys at https://www.google.com/recaptcha/admin.

reCaptcha requires more steps to display the captcha which are

Insert the Google reCaptcha API script to the page
Add data-sitekey attribute to the element

You DO NOT have to do these steps because they are done automatically by the add-on.

<!-- DO NOT need to add to your page -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<div id="captchaContainer" data-sitekey="..."></div>

In short, all you need are the site and secret keys provided by reCaptcha.

Including the add-on

Download reCaptcha2 add-on
Include reCaptcha2.min.js (located in the dist directory) to your page. Ensure that it's placed after formValidation(.min).js

<!-- FormValidation plugin -->
<script src="/vendor/formvalidation/dist/js/formValidation.min.js"></script>

<!-- Add-ons. You should place it inside /vendor/formvalidation/dist/js/addons directory -->
<script src="/vendor/formvalidation/dist/js/addons/reCaptcha2.min.js"></script>

Calling the add-on

It's possible to call the add-on in both programmatic and declarative ways:

Programmatic code
Declarative code

$('#signUpForm').formValidation({
    framework: '...',
    icon: {
        ...
    },
    addOns: {
        reCaptcha2: {
            element: 'captchaContainer',
            language: 'en',
            theme: 'light',
            siteKey: '6LdgOwETAAAAALA9auuNVKFeXizXcYFrKOVC_vs-',
            timeout: 120,
            message: 'The captcha is not valid'
        }
    },
    fields: {
        ...
    }
});

If you want to use multiple add-ons, just simply separate them by a comma in data-fv-addons attribute:

data-fv-addons="i18n, mandatoryIcon, recaptcha2"

<form id="signUpForm" method="post" class="form-horizontal"
    data-fv-addons="reCaptcha2"
    data-fv-addons-recaptcha2-element="captchaContainer"
    data-fv-addons-recaptcha2-language="en"
    data-fv-addons-recaptcha2-theme="light"
    data-fv-addons-recaptcha2-sitekey="6LdgOwETAAAAALA9auuNVKFeXizXcYFrKOVC_vs-"
    data-fv-addons-recaptcha2-timeout="120"
    data-fv-addons-recaptcha2-message="The captcha is not valid">
    ...
</form>

The reCaptcha2 add-on provides the following options:

^* — Required option

Option	HTML attribute	Type	Description
`element`^*	`data-fv-addons-recaptcha2-element`	`String`	The ID of element showing the captcha
`language`	`data-fv-addons-recaptcha2-language`	`String`	The language code defined by reCAPTCHA
`message`^*	`data-fv-addons-recaptcha2-message`	`String`	The error message that will be shown in case the captcha is not valid. You don't need to define it if the back-end URL above returns the message
`siteKey`^*	`data-fv-addons-recaptcha2-sitekey`	`String`	The site key provided by Google
`sToken`	`data-fv-addons-recaptcha2-stoken`	`String`	The secure token
`theme`	`data-fv-addons-recaptcha2-theme`	`String`	The theme name provided by Google. It can be one of light default dark
`timeout`	`data-fv-addons-recaptcha2-timeout`	`Number`	The number of seconds that session will expire. After this amount of time, you will be asked to enter a new captcha. The default value is 120 (2 minutes)

API

Following is the list of methods provided directly by FormValidation.AddOn.reCaptcha2:

reset

reset(element^*) — Reset the captcha element. It reset the checkbox captcha element and generate a new captcha.

^* — Required option

Parameter	Type	Description
`element`^*	String	The ID of element showing the captcha

FormValidation.AddOn.reCaptcha2.reset('captchaContainer');

This method doesn't remove the feedback icon and validation messages of captcha. To do that, you need to call the resetForm() or resetField() method.

// Reset entire form
$(yourForm).formValidation('resetForm', true);

// Or just reset the captcha field
$(yourForm).formValidation('resetField', 'g-recaptcha-response', true);

See the Resetting the captcha for a simple usage.

Example

Below is the piece of code showing programmatic and declarative usages:

<!-- Include FormValidation files first -->

<!-- Then include reCaptcha2 add-on -->
<script src="/vendor/formvalidation/js/addons/reCaptcha2.min.js"></script>

<form id="signUpForm" method="post" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Username</label>
        <div class="col-xs-6">
            <input type="text" class="form-control" name="username" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Email address</label>
        <div class="col-xs-6">
            <input type="text" class="form-control" name="email" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Password</label>
        <div class="col-xs-6">
            <input type="password" class="form-control" name="password" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Captcha</label>
        <div class="col-xs-8">
            <!-- The captcha container -->
            <div id="captchaContainer"></div>
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-5 col-xs-offset-3">
            <button type="submit" class="btn btn-primary">Submit</button>
            <button type="button" class="btn btn-default" id="resetButton">Reset</button>
        </div>
    </div>
</form>

<script type="text/javascript">
$(document).ready(function() {
    $('#signUpForm').formValidation({
        framework: 'bootstrap',
        icon: {
            valid: 'glyphicon glyphicon-ok',
            invalid: 'glyphicon glyphicon-remove',
            validating: 'glyphicon glyphicon-refresh'
        },
        addOns: {
            reCaptcha2: {
                element: 'captchaContainer',
                theme: 'light',
                siteKey: '6LdgOwETAAAAALA9auuNVKFeXizXcYFrKOVC_vs-',
                timeout: 120,
                message: 'The captcha is not valid'
            }
        },
        fields: {
            username: {
                validators: {
                    notEmpty: {
                        message: 'The username is required'
                    },
                    stringLength: {
                        min: 6,
                        max: 30,
                        message: 'The username must be more than 6 and less than 30 characters long'
                    },
                    regexp: {
                        regexp: /^[a-zA-Z0-9_\.]+$/,
                        message: 'The username can only consist of alphabetical, number, dot and underscore'
                    }
                }
            },
            email: {
                validators: {
                    notEmpty: {
                        message: 'The email address is required'
                    },
                    emailAddress: {
                        message: 'The input is not a valid email address'
                    }
                }
            },
            password: {
                validators: {
                    notEmpty: {
                        message: 'The password is required'
                    },
                    different: {
                        field: 'username',
                        message: 'The password cannot be the same as username'
                    }
                }
            }
        }
    });

    $('#resetButton').on('click', function() {
        // Reset the recaptcha
        FormValidation.AddOn.reCaptcha2.reset('captchaContainer');

        // Reset form
        $('#signUpForm').formValidation('resetForm', true);
    });
});
</script>

<!-- FormValidation plugin and the class supports validating Bootstrap form -->
<script src="/vendor/formvalidation/dist/js/formValidation.min.js"></script>
<script src="/vendor/formvalidation/dist/js/framework/bootstrap.min.js"></script>

<!-- reCaptcha2 add-on -->
<script src="/vendor/formvalidation/dist/js/addons/reCaptcha2.min.js"></script>

<form id="signUpForm" method="post" class="form-horizontal"
    data-fv-addons="reCaptcha2"
    data-fv-addons-recaptcha2-element="captchaContainer"
    data-fv-addons-recaptcha2-theme="light"
    data-fv-addons-recaptcha2-timeout="120"
    data-fv-addons-recaptcha2-sitekey="6LdgOwETAAAAALA9auuNVKFeXizXcYFrKOVC_vs-"
    data-fv-addons-recaptcha2-message="The captcha is not valid"

    data-fv-framework="bootstrap"
    data-fv-icon-valid="glyphicon glyphicon-ok"
    data-fv-icon-invalid="glyphicon glyphicon-remove"
    data-fv-icon-validating="glyphicon glyphicon-refresh">

    <div class="form-group">
        <label class="col-xs-3 control-label">Username</label>
        <div class="col-xs-6">
            <input type="text" class="form-control" name="username"
                data-fv-notempty="true"
                data-fv-notempty-message="The username is required"

                data-fv-stringlength="true"
                data-fv-stringlength-min="6"
                data-fv-stringlength-max="30"
                data-fv-stringlength-message="The username must be more than 6 and less than 30 characters long"

                data-fv-regexp="true"
                data-fv-regexp-regexp="^[a-zA-Z0-9_\.]+$"
                data-fv-regexp-message="The username can only consist of alphabetical, number, dot and underscore" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Email address</label>
        <div class="col-xs-6">
            <input type="text" class="form-control" name="email"
                data-fv-notempty="true"
                data-fv-notempty-message="The email address is required"

                data-fv-emailaddress="true"
                data-fv-emailaddress-message="The input is not a valid email address" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Password</label>
        <div class="col-xs-6">
            <input type="password" class="form-control" name="password"
                data-fv-notempty="true"
                data-fv-notempty-message="The password is required"

                data-fv-different="true"
                data-fv-different-field="username"
                data-fv-different-message="The password cannot be the same as username" />
        </div>
    </div>

    <div class="form-group">
        <label class="col-xs-3 control-label">Captcha</label>
        <div class="col-xs-8">
            <!-- The captcha container -->
            <div id="captchaContainer"></div>
        </div>
    </div>

    <div class="form-group">
        <div class="col-xs-5 col-xs-offset-3">
            <button type="submit" class="btn btn-primary">Submit</button>
            <button type="button" class="btn btn-default" id="resetButton">Reset</button>
        </div>
    </div>
</form>

<script type="text/javascript">
$(document).ready(function() {
    $('#signUpForm').formValidation();

    $('#resetButton').on('click', function() {
        // Reset the recaptcha
        FormValidation.AddOn.reCaptcha2.reset('captchaContainer');

        // Reset form
        $('#signUpForm').formValidation('resetForm', true);
    });
});
</script>

Showing message in a custom area

It's possible to place error message of the captcha in a custom area by using the err option.

Behind the scenes, the captcha field's name generated by Google reCaptcha is g-recaptcha-response, so we can apply the err option for this field as usual:

<form id="signUpForm" method="post" class="form-horizontal">
    <div class="form-group">
        <label class="col-xs-3 control-label">Captcha</label>
        <div class="col-xs-8">
            <!-- The captcha container -->
            <div id="captchaContainer"></div>
        </div>
    </div>

    <div class="form-group">
        <!-- The message container for captcha -->
        <div class="col-xs-8 col-xs-offset-3" id="captchaMessage">
        </div>
    </div>
</form>

<script>
$(document).ready(function() {
    $('#signUpForm').formValidation({
        ...
        addOns: {
            reCaptcha2: {
                element: 'captchaContainer',
                theme: 'light',
                siteKey: '6LdgOwETAAAAALA9auuNVKFeXizXcYFrKOVC_vs-',
                timeout: 120,
                message: 'The captcha is not valid'
            }
        },
        fields: {
            ...
            'g-recaptcha-response': {
                err: '#captchaMessage'
            }
        }
    });
});
</script>

Don't forget to wrap the captcha field's name (g-recaptcha-response) between single or double quote. See the Validating field with special name example for more use cases.

Resetting the captcha

If you want to reset the entire form including the feedback icon and messages, calling resetForm() doesn't enough.

In addition to that, we also need to call the reset() method:

$('#resetButton').on('click', function() {
    // Reset the recaptcha
    FormValidation.AddOn.reCaptcha2.reset('captchaContainer');

    // Reset form
    $('#signUpForm').formValidation('resetForm', true);
});

Click the Reset button in the example above to see how it works.

Change log

v0.4.0: Add reset() method to reset the captcha element
v0.3.1: Add sToken option
v0.3.0:
- Support multiple reCAPTCHA v2 elements on the same page
- Add Grunt build and minified files
v0.2.0: Add localization support
v0.1.0: First release