Using reCAPTCHA¶

Using reCAPTCHA validation in forms requires valid reCAPTCHA secret and site keys. You can get keys from https://www.google.com/recaptcha/.

The keys can be stored in either Django settings or site configuration settings. The keys for Django settings are:

RECAPTCHA_PUBLIC_KEY
RECPATCHA_PRIVATE_KEY

The equivalent site configuration keys are:

recaptcha_public_key
recaptcha_private_key

reCAPTCHA in Forms¶

If you want to use reCAPTCHA in a form, that form will have to inherit from the RecaptchaFormMixin (as well as Form). Your form can optionally provide a property, verify_recaptcha(), which will determine whether or not to validate the reCAPTCHA when the form is submitted. This can be used to optionally disable reCAPTCHA through a setting, for example.

Your form will require special rendering to use reCAPTCHA. The djblets_recaptcha template tag library includes two template tags to help with this:

recaptcha_js(), which renders the necessary JavaScript to use reCAPTCHA on the page. This should be included in the <head> of your document.
recaptcha_form_field(), which renders the actual reCAPTCHA field. This should be included in your form, before the <input type="submit"> tag.

Using Site Configuration¶

To use site configuration settings instead of Django settings, you will have to load the settings map for this module. This should happen once your app is initialized. An example using an django.apps.AppConfig follows:

from django.apps import AppConfig
from djblets.siteconfig.django_settings import (apply_django_settings,
                                                generate_defaults,
                                                get_django_defaults,
                                                get_django_settings_map)
from djblets.recaptcha import (defaults as recaptcha_defaults,
                               settings_map as recaptcha_settings_map)

class MyAppConfig(AppConfig):
    def ready(self):
        if not siteconfig.get_defaults():
            defaults = get_django_defaults()
            defaults.update(recaptcha_defaults)

            siteconfig.add_defaults(defaults)

        settings_map = get_django_settings_map()
        settings_map.update(recaptcha_settings_map)

        apply_django_settings(settings_map)

Using reCAPTCHA in a Form Template¶

If you are not using customized form rendering (i.e. you are rendering your form as {{form}} in your template, you can continue to do so; just ensure that the recaptcha_js() template tag appears in the document <head>. However, if you are rendering your form fields individually, you will have to use the recaptcha_form_field() template tag.

For example, consider the following form:

from django import forms
from django.forms import fields
from djblets.recaptcha.mixins import RecaptchaFormMixin


class RegistrationForm(RecaptchaFormMixin, forms.Form):
    username = fields.CharField(max_length=32,
                                label='Username')
    password = fields.CharField(min_length=8,
                                label='Password',
                                widget=forms.PasswordInput)

The following two templates can be used to render the form, assuming form is the instance of the form. The first template shows rendering using Django’s built-in form rendering:

{% load djblets_recaptcha %}

<!DOCTYPE html>
<html>
 <head>
  <title>Register</title>
  {% recaptcha_js %}
 </head>
 <body>
  {{form}}
 </body>
</html>

The second example shows how to use direct field rendering:

{% load djblets_recaptcha %}

<!DOCTYPE html>
<html>
 <head>
  <title>Register</title>
  {% recaptcha_js %}
 </head>
 <body>
  <form method="POST" action="." id="register-form">
   <div class="row">
    {{form.username.label_tag}}
    {{form.username}}
    {{form.errors.username
   </div>
   <div class="row">
    {{form.password.label_tag}}
    {{form.password}}
    {{form.errors.password}}
   </div>
   <div class="row">
    {% recaptcha_form_field form %}
   </div>
   <div class="row">
    <input type="submit" value="Register">
   </div>
  </form>
 </body>
</html>

Styling reCAPTCHA fields¶

The reCAPTCHA field will render as a <div> element with the class g-recaptcha if you wish to style it.