|
| 1 | +# Django reCaptcha v3 [](https://travis-ci.org/kbytesys/django-recaptcha2) |
| 2 | +---- |
| 3 | + |
| 4 | +This integration app implements a recaptcha field for <a href="https://developers.google.com/recaptcha/intro">Google reCaptcha v3</a>. |
| 5 | + |
| 6 | +**Warning:** this package is not suitable for production yet (also Google reCaptcha v3 is only in beta at the moment) |
| 7 | + |
| 8 | +**Warning2:** this package is **not** compatible with django-recaptcha2 |
| 9 | + |
| 10 | +---- |
| 11 | + |
| 12 | +## How to install |
| 13 | + |
| 14 | +Install the required package from pip (or take the source and install it by yourself): |
| 15 | + |
| 16 | +```bash |
| 17 | +pip install django-recaptcha3 |
| 18 | +``` |
| 19 | + |
| 20 | +Then add django-recaptcha3 to your installed apps: |
| 21 | + |
| 22 | +```python |
| 23 | +INSTALLED_APPS = ( |
| 24 | + ... |
| 25 | + 'snowpenguin.django.recaptcha3', |
| 26 | + ... |
| 27 | +) |
| 28 | +``` |
| 29 | + |
| 30 | +And add your reCaptcha private and public key to your django settings.py and the default action name: |
| 31 | + |
| 32 | +```python |
| 33 | +RECAPTCHA_PRIVATE_KEY = 'your private key' |
| 34 | +RECAPTCHA_PUBLIC_KEY = 'your public key' |
| 35 | +RECAPTCHA_DEFAULT_ACTION = 'generic' |
| 36 | + |
| 37 | +``` |
| 38 | + |
| 39 | +If you have to create the apikey for the domains managed by your django project, you can visit this <a href="https://www.google.com/recaptcha/admin">website</a>. |
| 40 | + |
| 41 | +## Usage |
| 42 | +### Form and Widget |
| 43 | +You can simply create a reCaptcha enabled form with the field provided by this app: |
| 44 | + |
| 45 | +```python |
| 46 | +from snowpenguin.django.recaptcha2.fields import ReCaptchaField |
| 47 | + |
| 48 | +class ExampleForm(forms.Form): |
| 49 | + [...] |
| 50 | + captcha = ReCaptchaField() |
| 51 | + [...] |
| 52 | +``` |
| 53 | + |
| 54 | +You can set the private key on the "private_key" argument of the field contructor if you want to override the one inside |
| 55 | +your configuration. |
| 56 | + |
| 57 | +### Templating |
| 58 | +You can use some template tags to simplify the reCaptcha adoption: |
| 59 | + |
| 60 | +* recaptcha_init: add the script tag for reCaptcha api. You have to put this tag somewhere in your "head" element |
| 61 | +* recaptcha_ready: call the execute function when the api script is loaded |
| 62 | +* recaptcha_execute: start the reCaptcha check and set the token from the api in your django forms |
| 63 | +* recaptcha_key: if you want to use reCaptcha manually in your template, you will need the sitekey (a.k.a. public api key). |
| 64 | + This tag returns a string with the configured public key. |
| 65 | + |
| 66 | +You can use the form as usual. |
| 67 | + |
| 68 | +### Samples |
| 69 | +#### Simple |
| 70 | + |
| 71 | +Just create a form with the reCaptcha field and follow this template example: |
| 72 | + |
| 73 | +```django |
| 74 | +{% load recaptcha3 %} |
| 75 | +<html> |
| 76 | + <head> |
| 77 | + {% recaptcha_init %} |
| 78 | + {% recaptcha_ready action_name='homepage' %} |
| 79 | + </head> |
| 80 | + <body> |
| 81 | + <form action="?" method="POST"> |
| 82 | + {% csrf_token %} |
| 83 | + {{ form }} |
| 84 | + <input type="submit" value="Submit"> |
| 85 | + </form> |
| 86 | + </body> |
| 87 | +</html> |
| 88 | +``` |
| 89 | + |
| 90 | +#### Custom callback |
| 91 | + |
| 92 | +The callback can be used to allow to use the token received from the api in ajax calls or whatever |
| 93 | + |
| 94 | +```django |
| 95 | +{% load recaptcha3 %} |
| 96 | +<html> |
| 97 | + <head> |
| 98 | + <script> |
| 99 | + function alertToken(token) { |
| 100 | + alert(token); |
| 101 | + } |
| 102 | + </script> |
| 103 | + {% recaptcha_init %} |
| 104 | + {% recaptcha_ready action_name='homepage' custom_callback='alertToken' %} |
| 105 | + </head> |
| 106 | + <body> |
| 107 | + <form action="?" method="POST"> |
| 108 | + {% csrf_token %} |
| 109 | + {{ form }} |
| 110 | + <input type="submit" value="Submit"> |
| 111 | + </form> |
| 112 | + </body> |
| 113 | +</html> |
| 114 | +``` |
| 115 | + |
| 116 | +#### Multiple render example |
| 117 | + |
| 118 | +You can render multiple reCaptcha without any extra effort: |
| 119 | + |
| 120 | +```django |
| 121 | +{% load recaptcha3 %} |
| 122 | +<html> |
| 123 | + <head> |
| 124 | + {% recaptcha_init %} |
| 125 | + {% recaptcha_ready action_name='homepage' %} |
| 126 | + </head> |
| 127 | + <body> |
| 128 | + <form action="?" method="POST"> |
| 129 | + {% csrf_token %} |
| 130 | + {{ form1 }} |
| 131 | + <input type="submit" value="Submit"> |
| 132 | + </form> |
| 133 | + <form action="?" method="POST"> |
| 134 | + {% csrf_token %} |
| 135 | + {{ form2 }} |
| 136 | + <input type="submit" value="Submit"> |
| 137 | + </form> |
| 138 | + </body> |
| 139 | +</html> |
| 140 | +``` |
| 141 | + |
| 142 | +#### Bare metal! |
| 143 | + |
| 144 | +You can use the plain javascript, just remember to set the correct value for the hidden field in the form |
| 145 | + |
| 146 | +```django |
| 147 | +<html> |
| 148 | + <head> |
| 149 | + <script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script> |
| 150 | + <script> |
| 151 | + grecaptcha.ready(function() { |
| 152 | + grecaptcha.execute('reCAPTCHA_site_key', {action: 'homepage'}).then(function(token) { |
| 153 | + document.querySelectorAll('input.django-recaptcha-hidden-field').forEach(function (value) { |
| 154 | + value.value = token; |
| 155 | + }); |
| 156 | + return token; |
| 157 | + }); |
| 158 | + }); |
| 159 | + </script> |
| 160 | + </head> |
| 161 | + <body> |
| 162 | + <form action="?" method="POST"> |
| 163 | + {% csrf_token %} |
| 164 | + {{ form }} |
| 165 | + <input type="submit" value="Submit"> |
| 166 | + </form> |
| 167 | + </body> |
| 168 | +</html> |
| 169 | +``` |
| 170 | + |
| 171 | +## Testing |
| 172 | +### Test unit support |
| 173 | +You can't simulate api calls in your test, but you can disable the recaptcha field and let your test works. |
| 174 | + |
| 175 | +Just set the RECAPTCHA_DISABLE env variable in your test: |
| 176 | + |
| 177 | +```python |
| 178 | +os.environ['RECAPTCHA_DISABLE'] = 'True' |
| 179 | +``` |
| 180 | + |
| 181 | +Warning: you can use any word in place of "True", the clean function will check only if the variable exists. |
| 182 | + |
| 183 | +### Test unit with recaptcha2 disabled |
| 184 | +```python |
| 185 | +import os |
| 186 | +import unittest |
| 187 | + |
| 188 | +from yourpackage.forms import MyForm |
| 189 | + |
| 190 | +class TestCase(unittest.TestCase): |
| 191 | + def setUp(self): |
| 192 | + os.environ['RECAPTCHA_DISABLE'] = 'True' |
| 193 | + |
| 194 | + def test_myform(self): |
| 195 | + form = MyForm({ |
| 196 | + 'field1': 'field1_value' |
| 197 | + }) |
| 198 | + self.assertTrue(form.is_valid()) |
| 199 | + |
| 200 | + def tearDown(self): |
| 201 | + del os.environ['RECAPTCHA_DISABLE'] |
| 202 | +``` |
0 commit comments