0
# Form Integration
1
2
Django Simple Captcha provides seamless integration with Django forms through dedicated form fields and widgets. The `CaptchaField` automatically handles validation while the widget system manages the visual presentation and user interaction.
3
4
## Capabilities
5
6
### CaptchaField
7
8
Main form field class that provides automatic captcha validation as part of Django's form processing pipeline.
9
10
```python { .api }
11
class CaptchaField(MultiValueField):
12
def __init__(*args, **kwargs):
13
"""
14
Initialize captcha field.
15
16
Parameters:
17
- widget: CaptchaTextInput instance (optional)
18
- id_prefix: str, prefix for HTML element IDs (optional)
19
- generator: str/callable, challenge generator function (optional)
20
"""
21
22
def compress(data_list):
23
"""
24
Join field values with comma separator.
25
26
Parameters:
27
- data_list: list, form field values
28
29
Returns:
30
str: Comma-separated values
31
"""
32
33
def clean(value):
34
"""
35
Validate captcha response against stored challenge.
36
37
Parameters:
38
- value: str, user-submitted captcha response
39
40
Returns:
41
str: Validated response
42
43
Raises:
44
ValidationError: If captcha response is invalid or expired
45
"""
46
```
47
48
### CaptchaTextInput Widget
49
50
Primary widget for rendering captcha with image, input field, and optional refresh functionality.
51
52
```python { .api }
53
class CaptchaTextInput(BaseCaptchaTextInput):
54
def __init__(attrs=None, id_prefix=None, generator=None):
55
"""
56
Initialize captcha widget.
57
58
Parameters:
59
- attrs: dict, HTML attributes for widget (optional)
60
- id_prefix: str, prefix for HTML element IDs (optional)
61
- generator: str/callable, challenge generator function (optional)
62
"""
63
64
def render(name, value, attrs=None, renderer=None):
65
"""
66
Render complete captcha widget HTML.
67
68
Parameters:
69
- name: str, field name
70
- value: str, current field value
71
- attrs: dict, HTML attributes (optional)
72
- renderer: renderer instance (optional)
73
74
Returns:
75
str: Rendered HTML for captcha widget
76
"""
77
78
def get_context(name, value, attrs):
79
"""
80
Build context variables for template rendering.
81
82
Parameters:
83
- name: str, field name
84
- value: str, current field value
85
- attrs: dict, HTML attributes
86
87
Returns:
88
dict: Template context with image_url, audio_url, refresh_url, etc.
89
"""
90
```
91
92
### Widget Components
93
94
Supporting widget classes for specific input elements within the captcha widget.
95
96
```python { .api }
97
class CaptchaHiddenInput(HiddenInput):
98
def build_attrs():
99
"""
100
Add autocomplete=off attribute to hidden input.
101
102
Returns:
103
dict: HTML attributes with autocomplete disabled
104
"""
105
106
class CaptchaAnswerInput(TextInput):
107
def build_attrs():
108
"""
109
Disable browser assistance features for captcha input.
110
111
Returns:
112
dict: HTML attributes with autocorrect, autocomplete, spellcheck disabled
113
"""
114
```
115
116
### Base Widget Functionality
117
118
Core widget functionality shared across captcha widget implementations.
119
120
```python { .api }
121
class BaseCaptchaTextInput(MultiWidget):
122
def fetch_captcha_store(name, value, attrs=None, generator=None):
123
"""
124
Create new captcha challenge and return store instance.
125
126
Parameters:
127
- name: str, field name
128
- value: str, current field value
129
- attrs: dict, HTML attributes (optional)
130
- generator: str/callable, challenge generator (optional)
131
132
Returns:
133
CaptchaStore: New captcha instance
134
"""
135
136
def image_url():
137
"""
138
Get URL for captcha image.
139
140
Returns:
141
str: Image URL path
142
"""
143
144
def audio_url():
145
"""
146
Get URL for captcha audio file.
147
148
Returns:
149
str: Audio URL path
150
"""
151
152
def refresh_url():
153
"""
154
Get URL for AJAX captcha refresh.
155
156
Returns:
157
str: Refresh endpoint URL
158
"""
159
160
def decompress(value):
161
"""
162
Split comma-separated captcha value into components.
163
164
Parameters:
165
- value: str, comma-separated captcha value
166
167
Returns:
168
list: Split components [hashkey, response]
169
"""
170
171
def id_for_label(id_):
172
"""
173
Generate proper label ID for accessibility.
174
175
Parameters:
176
- id_: str, base element ID
177
178
Returns:
179
str: Label-compatible ID
180
"""
181
```
182
183
## Usage Examples
184
185
### Basic Form Integration
186
187
```python
188
from django import forms
189
from captcha.fields import CaptchaField
190
191
class CommentForm(forms.Form):
192
name = forms.CharField(max_length=100)
193
email = forms.EmailField()
194
comment = forms.CharField(widget=forms.Textarea)
195
captcha = CaptchaField()
196
```
197
198
### Custom Widget Configuration
199
200
```python
201
from captcha.fields import CaptchaField, CaptchaTextInput
202
203
class RegistrationForm(forms.Form):
204
username = forms.CharField(max_length=30)
205
password = forms.CharField(widget=forms.PasswordInput)
206
# Custom captcha widget with specific generator
207
captcha = CaptchaField(
208
widget=CaptchaTextInput(
209
attrs={'class': 'form-control'},
210
id_prefix='registration',
211
generator='captcha.helpers.math_challenge'
212
)
213
)
214
```
215
216
### Model Form Integration
217
218
```python
219
from django import forms
220
from django.contrib.auth.models import User
221
from captcha.fields import CaptchaField
222
223
class UserCreationForm(forms.ModelForm):
224
captcha = CaptchaField()
225
226
class Meta:
227
model = User
228
fields = ['username', 'email', 'password']
229
```