Field

The quickest way to add reCAPTHCA to a form is to use the included ReCaptchaField field type. A ReCaptcha widget will be rendered with the field validating itself without any further action required from you. For example:

from django import forms
from captcha.fields import ReCaptchaField

class FormWithCaptcha(forms.Form):
    captcha = ReCaptchaField()

To allow for runtime specification of keys and SSL usage you can optionally pass private_key, public_key or use_ssl parameters to the constructor, i.e.:

captcha = ReCaptchaField(
    public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',
    private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',
    use_ssl=True
)

If specified these parameters will be used instead of your reCAPCTHA project settings.

The reCAPTCHA widget supports several Javascript options variables customizing the behaviour of the widget, such as theme and lang. You can forward these options to the widget by passing an attr parameter containing a dictionary of options to ReCaptchaField, i.e.:

captcha = ReCaptchaField(attrs={'theme' : 'clean'})

The captcha client takes the key/value pairs for the options key, iterates over them and writes out the RecaptchaOptions value in JavaScript.

django-registration

django-recaptcha ships with a django-registration backend extending the default backend to include a reCAPTCHA field. This is included mostly as an example of how you could intergrate a reCAPTCHA field with django-registration. I suggest you familiarize yourself with the django-registration docs for more comprehensive documentation.

To use the reCAPTHCA backend complete these steps:

1. Add registration to your INSTALLED_APPS setting.

2. Add captcha registration backend url include to your project's urls.py file:

   (r'^accounts/', include('captcha.backends.default.urls')),
   

3. Add an ACCOUNT_ACTIVATION_DAYS setting to the project's settings.py file. This is the number of days users will have to activate their accounts after registering, as required by django-registration, i.e.:

   ACCOUNT_ACTIVATION_DAYS = 7
   

4. Implement the various templates as required by django-registration.

Once done you should be able to access /accounts/register/ and see the reCAPTCHA field in action as part of the registration process.