Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kbytesys/django-recaptcha2

Django reCaptcha v2 field/widget
https://github.com/kbytesys/django-recaptcha2

Last synced: 3 days ago
JSON representation

Django reCaptcha v2 field/widget

Awesome Lists containing this project

README 

        
# Django reCaptcha v2 [![Build Status](https://travis-ci.org/kbytesys/django-recaptcha2.svg?branch=master)](https://travis-ci.org/kbytesys/django-recaptcha2)

----



This integration app implements a recaptcha field for Google reCaptcha v2

with explicit rendering and multiple recaptcha support. The invisible version of the reCAPTCHA with the automatic render mode

is now supported, please read the related documentation below.



Are you looking for the Google reCaptcha v3? Take a look to the dedicated repository https://github.com/kbytesys/django-recaptcha3



----



## How to install



Install the required package from pip (or take the source and install it by yourself):



```bash

pip install django-recaptcha2

```



Then add django-recaptcha2 to your installed apps:



```python

INSTALLED_APPS = (

    ...

    'snowpenguin.django.recaptcha2',

    ...

)

```



And add your reCaptcha private and public key to your django settings.py:



```python

RECAPTCHA_PRIVATE_KEY = 'your private key'

RECAPTCHA_PUBLIC_KEY = 'your public key'

# If you require reCaptcha to be loaded from somewhere other than https://google.com

# (e.g. to bypass firewall restrictions), you can specify what proxy to use.

# RECAPTCHA_PROXY_HOST = 'https://recaptcha.net'

```



If you have to create the apikey for the domains managed by your django project, you can visit this website.



## "I'm not a robot" Usage 

### Form and Widget

You can simply create a reCaptcha enabled form with the field provided by this app:



```python

from snowpenguin.django.recaptcha2.fields import ReCaptchaField

from snowpenguin.django.recaptcha2.widgets import ReCaptchaWidget



class ExampleForm(forms.Form):

    [...]

    captcha = ReCaptchaField(widget=ReCaptchaWidget())

    [...]

```



You can set the private key on the "private_key" argument of the field contructor and you can pass some

parameters into the widget contructor:



```python

class ReCaptchaWidget(Widget):

    def __init__(self, explicit=False, container_id=None, theme=None, type=None, size=None, tabindex=None,

                 callback=None, expired_callback=None, attrs={}, *args, **kwargs):

```



If you set the explicit boolean to true, you will render this field with explicit render support. This is useful if you

want to use multiple forms with reCaptcha in one page. Take a look to template and samples sections for more info.



You can personalize reCaptcha theme, type, size, tabindex, callback and expired_callback parameters. Look the reCaptcha

documentation if you want to change those values.

Warning: the app doesn't validate the incoming parameter values.



### Recaptcha "container id"

Now the default container id for the recaptcha is:



* recaptcha-{$fieldname} for the automatic rendering

* recaptcha-{$fieldname}-{%fiverandomdigits} for the explicit rendering



This avoids name collisions when you use multiple instances of the recaptcha in different forms, but in the same page

and with the same field name.



**Note:** you can always override the container id with the "container_id" argument in the widget constructor, but take

care: nobody will check if the id you provide is already used.



### Templating

You can use some template tags to simplify the reCaptcha adoption:

 

* recaptcha_init: add the script tag for reCaptcha api. You have to put this tag somewhere in your "head" element

* recaptcha_explicit_init: add the script tag for the reCaptcha api with explicit render support. You have to put this

  tag somewhere above the end of your "body" element. If you use this tag, you don't have to use "recaptcha_init".

* recaptcha_explicit_support: this tag add the callback function used by reCaptcha for explicit rendering. This tag also

  add some funcitions and javascript vars used by the ReCaptchaWidget when it is initialized with explicit=True. You have

  to put this tag somewhere in your "head" element.

* recaptcha_key: if you want to use reCaptcha manually in your template, you will need the sitekey (a.k.a. public api key).

  This tag returns a string with the configured public key.

  

You can use the form as usual.



### Force widget language

You can disable the language auto-detection in the recaptha2 init tag:



```django

{% load recaptcha2 %}



  

      {% recaptcha_init 'es' %}

  

```



or



```django

    

    {% recaptcha_explicit_init 'es'%}

  



    

      {% csrf_token %}

      {{ form }}

      

    

  

    

      {% csrf_token %}

      {{ form }}

      

    

    {% recaptcha_explicit_init %}

  

    

      {% csrf_token %}

      {{ form1 }}

      

    

    

      {% csrf_token %}

      {{ form2 }}

      

    

    {% recaptcha_explicit_init %}

  

        [...]

        


        

            django_recaptcha_callbacks.push(function() {

                grecaptcha.render('recaptcha', {

                    'theme': 'dark',

                    'sitekey': '{% recaptcha_key %}'

                })

            });

        

        [...]

        {% recaptcha_explicit_init %}

    

    

      {% csrf_token %}

      {{ form }}

      {% recaptcha_invisible_button submit_label='Submit' %}

    

  

    

      {% csrf_token %}

      {{ form }}

      {% recaptcha_invisible_button submit_label='Submit' form_id='myform' %}

    

  

    

      {% csrf_token %}

      {{ form }}

      {% recaptcha_invisible_button submit_label='Submit' custom_callback='mycallback' %}

      

          function mycallback(token) {

              someFunction();

              document.getElementById("myform").submit();

          }