Form and field validation¶
Form validation happens when the data is cleaned. If you want to customize
this process, there are various places to make changes, each one serving a
different purpose. Three types of cleaning methods are run during form
processing. These are normally executed when you call the is_valid()
method on a form. There are other things that can also trigger cleaning and
validation (accessing the errors
attribute or calling full_clean()
directly), but normally they won’t be needed.
In general, any cleaning method can raise ValidationError
if there is a
problem with the data it is processing, passing the relevant information to
the ValidationError
constructor. See below
for the best practice in raising ValidationError
. If no ValidationError
is raised, the method should return the cleaned (normalized) data as a Python
object.
Most validation can be done using validators — helpers that can be reused.
Validators are functions (or callables) that take a single argument and raise
ValidationError
on invalid input. Validators are run after the field’s
to_python
and validate
methods have been called.
Validation of a form is split into several steps, which can be customized or
overridden:
-
The
to_python()
method on aField
is the first step in every
validation. It coerces the value to a correct datatype and raises
ValidationError
if that is not possible. This method accepts the raw
value from the widget and returns the converted value. For example, a
FloatField
will turn the data into a Pythonfloat
or raise a
ValidationError
. -
The
validate()
method on aField
handles field-specific validation
that is not suitable for a validator. It takes a value that has been
coerced to a correct datatype and raisesValidationError
on any error.
This method does not return anything and shouldn’t alter the value. You
should override it to handle validation logic that you can’t or don’t
want to put in a validator. -
The
run_validators()
method on aField
runs all of the field’s
validators and aggregates all the errors into a single
ValidationError
. You shouldn’t need to override this method. -
The
clean()
method on aField
subclass is responsible for running
to_python()
,validate()
, andrun_validators()
in the correct
order and propagating their errors. If, at any time, any of the methods
raiseValidationError
, the validation stops and that error is raised.
This method returns the clean data, which is then inserted into the
cleaned_data
dictionary of the form. -
The
clean_<fieldname>()
method is called on a form subclass – where
<fieldname>
is replaced with the name of the form field attribute.
This method does any cleaning that is specific to that particular
attribute, unrelated to the type of field that it is. This method is not
passed any parameters. You will need to look up the value of the field
inself.cleaned_data
and remember that it will be a Python object
at this point, not the original string submitted in the form (it will be
incleaned_data
because the general fieldclean()
method, above,
has already cleaned the data once).For example, if you wanted to validate that the contents of a
CharField
calledserialnumber
was unique,
clean_serialnumber()
would be the right place to do this. You don’t
need a specific field (it’s aCharField
), but you want a
formfield-specific piece of validation and, possibly, cleaning/normalizing
the data.The return value of this method replaces the existing value in
cleaned_data
, so it must be the field’s value fromcleaned_data
(even
if this method didn’t change it) or a new cleaned value. -
The form subclass’s
clean()
method can perform validation that requires
access to multiple form fields. This is where you might put in checks such as
“if fieldA
is supplied, fieldB
must contain a valid email address”.
This method can return a completely different dictionary if it wishes, which
will be used as thecleaned_data
.Since the field validation methods have been run by the time
clean()
is
called, you also have access to the form’serrors
attribute which
contains all the errors raised by cleaning of individual fields.Note that any errors raised by your
Form.clean()
override will not
be associated with any field in particular. They go into a special
“field” (called__all__
), which you can access via the
non_field_errors()
method if you need to. If you
want to attach errors to a specific field in the form, you need to call
add_error()
.Also note that there are special considerations when overriding
theclean()
method of aModelForm
subclass. (see the
ModelForm documentation for more information)
These methods are run in the order given above, one field at a time. That is,
for each field in the form (in the order they are declared in the form
definition), the Field.clean()
method (or its override) is run, then
clean_<fieldname>()
. Finally, once those two methods are run for every
field, the Form.clean()
method, or its override, is executed whether
or not the previous methods have raised errors.
Examples of each of these methods are provided below.
As mentioned, any of these methods can raise a ValidationError
. For any
field, if the Field.clean()
method raises a ValidationError
, any
field-specific cleaning method is not called. However, the cleaning methods
for all remaining fields are still executed.
Raising ValidationError
¶
In order to make error messages flexible and easy to override, consider the
following guidelines:
-
Provide a descriptive error
code
to the constructor:# Good ValidationError(_("Invalid value"), code="invalid") # Bad ValidationError(_("Invalid value"))
-
Don’t coerce variables into the message; use placeholders and the
params
argument of the constructor:# Good ValidationError( _("Invalid value: %(value)s"), params={"value": "42"}, ) # Bad ValidationError(_("Invalid value: %s") % value)
-
Use mapping keys instead of positional formatting. This enables putting
the variables in any order or omitting them altogether when rewriting the
message:# Good ValidationError( _("Invalid value: %(value)s"), params={"value": "42"}, ) # Bad ValidationError( _("Invalid value: %s"), params=("42",), )
-
Wrap the message with
gettext
to enable translation:# Good ValidationError(_("Invalid value")) # Bad ValidationError("Invalid value")
Putting it all together:
raise ValidationError( _("Invalid value: %(value)s"), code="invalid", params={"value": "42"}, )
Following these guidelines is particularly necessary if you write reusable
forms, form fields, and model fields.
While not recommended, if you are at the end of the validation chain
(i.e. your form clean()
method) and you know you will never need
to override your error message you can still opt for the less verbose:
ValidationError(_("Invalid value: %s") % value)
The Form.errors.as_data()
and
Form.errors.as_json()
methods
greatly benefit from fully featured ValidationError
s (with a code
name
and a params
dictionary).
Raising multiple errors¶
If you detect multiple errors during a cleaning method and wish to signal all
of them to the form submitter, it is possible to pass a list of errors to the
ValidationError
constructor.
As above, it is recommended to pass a list of ValidationError
instances
with code
s and params
but a list of strings will also work:
# Good raise ValidationError( [ ValidationError(_("Error 1"), code="error1"), ValidationError(_("Error 2"), code="error2"), ] ) # Bad raise ValidationError( [ _("Error 1"), _("Error 2"), ] )
Using validation in practice¶
The previous sections explained how validation works in general for forms.
Since it can sometimes be easier to put things into place by seeing each
feature in use, here are a series of small examples that use each of the
previous features.
Using validators¶
Django’s form (and model) fields support use of utility functions and classes
known as validators. A validator is a callable object or function that takes a
value and returns nothing if the value is valid or raises a
ValidationError
if not. These can be passed to a
field’s constructor, via the field’s validators
argument, or defined on the
Field
class itself with the default_validators
attribute.
Validators can be used to validate values inside the field, let’s have a look
at Django’s SlugField
:
from django.core import validators from django.forms import CharField class SlugField(CharField): default_validators = [validators.validate_slug]
As you can see, SlugField
is a CharField
with a customized validator
that validates that submitted text obeys to some character rules. This can also
be done on field definition so:
is equivalent to:
slug = forms.CharField(validators=[validators.validate_slug])
Common cases such as validating against an email or a regular expression can be
handled using existing validator classes available in Django. For example,
validators.validate_slug
is an instance of
a RegexValidator
constructed with the first
argument being the pattern: ^[-a-zA-Z0-9_]+$
. See the section on
writing validators to see a list of what is already
available and for an example of how to write a validator.
Form field default cleaning¶
Let’s first create a custom form field that validates its input is a string
containing comma-separated email addresses. The full class looks like this:
from django import forms from django.core.validators import validate_email class MultiEmailField(forms.Field): def to_python(self, value): """Normalize data to a list of strings.""" # Return an empty list if no input was given. if not value: return [] return value.split(",") def validate(self, value): """Check if value consists only of valid emails.""" # Use the parent's handling of required fields, etc. super().validate(value) for email in value: validate_email(email)
Every form that uses this field will have these methods run before anything
else can be done with the field’s data. This is cleaning that is specific to
this type of field, regardless of how it is subsequently used.
Let’s create a ContactForm
to demonstrate how you’d use this field:
class ContactForm(forms.Form): subject = forms.CharField(max_length=100) message = forms.CharField() sender = forms.EmailField() recipients = MultiEmailField() cc_myself = forms.BooleanField(required=False)
Use MultiEmailField
like any other form field. When the is_valid()
method is called on the form, the MultiEmailField.clean()
method will be
run as part of the cleaning process and it will, in turn, call the custom
to_python()
and validate()
methods.
Cleaning a specific field attribute¶
Continuing on from the previous example, suppose that in our ContactForm
,
we want to make sure that the recipients
field always contains the address
"fred@example.com"
. This is validation that is specific to our form, so we
don’t want to put it into the general MultiEmailField
class. Instead, we
write a cleaning method that operates on the recipients
field, like so:
from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean_recipients(self): data = self.cleaned_data["recipients"] if "fred@example.com" not in data: raise ValidationError("You have forgotten about Fred!") # Always return a value to use as the new cleaned data, even if # this method didn't change it. return data
Cleaning and validating fields that depend on each other¶
Suppose we add another requirement to our contact form: if the cc_myself
field is True
, the subject
must contain the word "help"
. We are
performing validation on more than one field at a time, so the form’s
clean()
method is a good spot to do this. Notice that we are
talking about the clean()
method on the form here, whereas earlier we were
writing a clean()
method on a field. It’s important to keep the field and
form difference clear when working out where to validate things. Fields are
single data points, forms are a collection of fields.
By the time the form’s clean()
method is called, all the individual field
clean methods will have been run (the previous two sections), so
self.cleaned_data
will be populated with any data that has survived so
far. So you also need to remember to allow for the fact that the fields you
are wanting to validate might not have survived the initial individual field
checks.
There are two ways to report any errors from this step. Probably the most
common method is to display the error at the top of the form. To create such
an error, you can raise a ValidationError
from the clean()
method. For
example:
from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() cc_myself = cleaned_data.get("cc_myself") subject = cleaned_data.get("subject") if cc_myself and subject: # Only do something if both fields are valid so far. if "help" not in subject: raise ValidationError( "Did not send for 'help' in the subject despite " "CC'ing yourself." )
In this code, if the validation error is raised, the form will display an
error message at the top of the form (normally) describing the problem. Such
errors are non-field errors, which are displayed in the template with
{{ form.non_field_errors }}
.
The call to super().clean()
in the example code ensures that any validation
logic in parent classes is maintained. If your form inherits another that
doesn’t return a cleaned_data
dictionary in its clean()
method (doing
so is optional), then don’t assign cleaned_data
to the result of the
super()
call and use self.cleaned_data
instead:
def clean(self): super().clean() cc_myself = self.cleaned_data.get("cc_myself") ...
The second approach for reporting validation errors might involve assigning the
error message to one of the fields. In this case, let’s assign an error message
to both the “subject” and “cc_myself” rows in the form display. Be careful when
doing this in practice, since it can lead to confusing form output. We’re
showing what is possible here and leaving it up to you and your designers to
work out what works effectively in your particular situation. Our new code
(replacing the previous sample) looks like this:
from django import forms class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() cc_myself = cleaned_data.get("cc_myself") subject = cleaned_data.get("subject") if cc_myself and subject and "help" not in subject: msg = "Must put 'help' in subject when cc'ing yourself." self.add_error("cc_myself", msg) self.add_error("subject", msg)
The second argument of add_error()
can be a string, or preferably an
instance of ValidationError
. See Raising ValidationError for more
details. Note that add_error()
automatically removes the field from
cleaned_data
.
In Django forms, it can check whether the form is valid:
if form.is_valid():
return HttpResponseRedirect('/thanks/')
But I’m missing what to do if it isn’t valid? How do I return the form with the error messages? I’m not seeing the «else» in any of the examples.
alias51
8,01822 gold badges93 silver badges165 bronze badges
asked Feb 1, 2013 at 13:48
user984003user984003
27.7k63 gold badges186 silver badges281 bronze badges
If you render the same view when the form is not valid then in template you can access the form errors using form.errors
.
{% if form.errors %}
{% for field in form %}
{% for error in field.errors %}
<div class="alert alert-danger">
<strong>{{ error|escape }}</strong>
</div>
{% endfor %}
{% endfor %}
{% for error in form.non_field_errors %}
<div class="alert alert-danger">
<strong>{{ error|escape }}</strong>
</div>
{% endfor %}
{% endif %}
An example:
def myView(request):
form = myForm(request.POST or None, request.FILES or None)
if request.method == 'POST':
if form.is_valid():
return HttpResponseRedirect('/thanks/')
return render(request, 'my_template.html', {'form': form})
melwil
2,5471 gold badge19 silver badges33 bronze badges
answered Feb 1, 2013 at 13:50
Aamir RindAamir Rind
38.6k23 gold badges125 silver badges163 bronze badges
6
views.py
from django.contrib import messages
def view_name(request):
if request.method == 'POST':
form = form_class(request.POST)
if form.is_valid():
return HttpResponseRedirect('/thanks'/)
else:
messages.error(request, "Error")
return render(request, 'page.html', {'form':form_class()})
If you want to show the errors of the form other than that not valid just put {{form.as_p}} like what I did below
page.html
<html>
<head>
<script>
{% if messages %}
{% for message in messages %}
alert('{{message}}')
{% endfor %}
{% endif %}
</script>
</head>
<body>
{{form.as_p}}
</body>
</html>
Drubio
1,1173 gold badges13 silver badges30 bronze badges
answered Feb 1, 2013 at 13:51
4
UPDATE:
Added a more detailed description of the formset errors.
Form.errors combines all field and non_field_errors. Therefore you can simplify the html to this:
template
{% load form_tags %}
{% if form.errors %}
<div class="alert alert-danger alert-dismissible col-12 mx-1" role="alert">
<div id="form_errors">
{% for key, value in form.errors.items %}
<span class="fieldWrapper">
{{ key }}:{{ value }}
</span>
{% endfor %}
</div>
<button type="button" class="close" data-dismiss="alert" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
{% endif %}
If you want to generalise it you can create a list_errors.html which you include in every form template. It handles form and formset errors:
{% if form.errors %}
<div class="alert alert-danger alert-dismissible col-12 mx-1" role="alert">
<div id="form_errors">
{% for key, value in form.errors.items %}
<span class="fieldWrapper">
{{ key }}:{{ value }}
</span>
{% endfor %}
</div>
<button type="button" class="close" data-dismiss="alert" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
{% elif formset.total_error_count %}
<div class="alert alert-danger alert-dismissible col-12 mx-1" role="alert">
<div id="form_errors">
{% if formset.non_form_errors %}
{{ formset.non_form_errors }}
{% endif %}
{% for form in formset.forms %}
{% if form.errors %}
Form number {{ forloop.counter }}:
<ul class="errorlist">
{% for key, error in form.errors.items %}
<li>{{form.fields|get_label:key}}
<ul class="errorlist">
<li>{{error}}</li>
</ul>
</li>
{% endfor %}
</ul>
{% endif %}
{% endfor %}
</div>
</div>
{% endif %}
form_tags.py
from django import template
register = template.Library()
def get_label(a_dict, key):
return getattr(a_dict.get(key), 'label', 'No label')
register.filter("get_label", get_label)
One caveat: In contrast to forms Formset.errors does not include non_field_errors.
answered Jan 14, 2020 at 11:10
P. MainoP. Maino
3031 gold badge3 silver badges11 bronze badges
def some_view(request):
if request.method == 'POST':
form = SomeForm(request.POST)
if form.is_valid():
return HttpResponseRedirect('/thanks'/)
else:
form = SomeForm()
return render(request, 'some_form.html', {'form': form})
answered Feb 1, 2013 at 13:58
Lukasz KoziaraLukasz Koziara
4,2745 gold badges32 silver badges43 bronze badges
1
This answer is correct but has a problem: fields not defined.
If you have more then one field, you can not recognize which one has error.
with this change you can display field name:
{% if form.errors %}
{% for field in form %}
{% for error in field.errors %}
<div class="alert alert-danger">
<strong>{{ field.label }}</strong><span>{{ error|escape }}</strong>
</div>
{% endfor %}
{% endfor %}
{% for error in form.non_field_errors %}
<div class="alert alert-danger">
<strong>{{ error|escape }}</strong>
</div>
{% endfor %}
{% endif %}
answered Feb 1, 2021 at 16:56
ChalistChalist
3,1405 gold badges39 silver badges68 bronze badges
@AamirAdnan’s answer missing field.label
; the other way to show the errors in few lines.
{% if form.errors %}
<!-- Error messaging -->
<div id="errors">
<div class="inner">
<p>There were some errors in the information you entered. Please correct the following:</p>
<ul>
{% for field in form %}
{% if field.errors %}<li>{{ field.label }}: {{ field.errors|striptags }}</li>{% endif %}
{% endfor %}
</ul>
</div>
</div>
<!-- /Error messaging -->
{% endif %}
answered Aug 25, 2020 at 7:09
1
simply you can do like this because when you initialized the form in contains form data and invalid data as well:
def some_func(request):
form = MyForm(request.POST)
if form.is_valid():
//other stuff
return render(request,template_name,{'form':form})
if will raise the error in the template if have any but the form data will still remain as :
error_demo_here
answered Mar 14, 2020 at 5:55
You can put simply a flag variable, in this case is_successed.
def preorder_view(request, pk, template_name='preorders/preorder_form.html'):
is_successed=0
formset = PreorderHasProductsForm(request.POST)
client= get_object_or_404(Client, pk=pk)
if request.method=='POST':
#populate the form with data from the request
# formset = PreorderHasProductsForm(request.POST)
if formset.is_valid():
is_successed=1
preorder_date=formset.cleaned_data['preorder_date']
product=formset.cleaned_data['preorder_has_products']
return render(request, template_name, {'preorder_date':preorder_date,'product':product,'is_successed':is_successed,'formset':formset})
return render(request, template_name, {'object':client,'formset':formset})
afterwards in your template you can just put the code below
{%if is_successed == 1 %}
<h1>{{preorder_date}}</h1>
<h2> {{product}}</h2>
{%endif %}
answered Nov 22, 2018 at 13:36
gtopalgtopal
5241 gold badge9 silver badges34 bronze badges
Валидация форм и полей¶
Валидация формы происходит при очистке данных. Если вы хотите настроить этот процесс, есть различные места для внесения изменений, каждое из которых служит для разных целей. В процессе обработки формы выполняются три типа методов очистки. Обычно они выполняются, когда вы вызываете метод is_valid()
на форме. Есть и другие вещи, которые также могут вызвать очистку и проверку (обращение к атрибуту errors
или прямой вызов full_clean()
), но обычно они не нужны.
В общем, любой метод очистки может поднять ValidationError
, если есть проблема с данными, которые он обрабатывает, передавая соответствующую информацию конструктору ValidationError
. See below для лучшей практики поднятия ValidationError
. Если не поднимается ValidationError
, метод должен вернуть очищенные (нормализованные) данные в виде объекта Python.
Большинство валидаций можно выполнить с помощью validators — помощников, которые можно использовать повторно. Валидаторы — это функции (или callables), которые принимают один аргумент и вызывают ValidationError
при недопустимом вводе. Валидаторы запускаются после вызова методов to_python
и validate
поля.
Валидация формы разбита на несколько этапов, которые можно настроить или отменить:
-
Метод
to_python()
наField
является первым шагом в каждой валидации. Он преобразует значение к правильному типу данных и выдает сообщениеValidationError
, если это невозможно. Этот метод принимает необработанное значение от виджета и возвращает преобразованное значение. Например,FloatField
превратит данные в Pythonfloat
или выдастValidationError
. -
Метод
validate()
наField
обрабатывает специфическую для поля валидацию, которая не подходит для валидатора. Он принимает значение, которое было приведено к правильному типу данных, и при любой ошибке выдает сообщениеValidationError
. Этот метод ничего не возвращает и не должен изменять значение. Вы должны переопределить его для обработки логики валидации, которую вы не можете или не хотите поместить в валидатор. -
Метод
run_validators()
на полеField
запускает все валидаторы поля и объединяет все ошибки в одинValidationError
. Вам не нужно переопределять этот метод. -
Метод
clean()
в подклассеField
отвечает за выполнениеto_python()
,validate()
иrun_validators()
в правильном порядке и распространение их ошибок. Если в любой момент времени какой-либо из методов вызывает ошибкуValidationError
, валидация останавливается, и эта ошибка выдается. Этот метод возвращает чистые данные, которые затем вставляются в словарьcleaned_data
формы. -
Метод
clean_<fieldname>()
вызывается на подклассе формы – где<fieldname>
заменяется на имя атрибута поля формы. Этот метод выполняет любую очистку, специфичную для данного атрибута, не связанную с типом поля, которым он является. Этому методу не передаются никакие параметры. Вам нужно будет найти значение поля вself.cleaned_data
и помнить, что в этот момент это будет объект Python, а не исходная строка, представленная в форме (она будет вcleaned_data
, потому что метод general fieldclean()
, описанный выше, уже однажды очистил данные).Например, если вы хотите проверить, что содержимое
CharField
под названиемserialnumber
является уникальным,clean_serialnumber()
будет подходящим местом для этого. Вам не нужно конкретное поле (этоCharField
), но вам нужен специфический для поля формы фрагмент проверки и, возможно, очистки/нормализации данных.Возвращаемое значение этого метода заменяет существующее значение в
cleaned_data
, поэтому это должно быть значение поля изcleaned_data
(даже если этот метод не изменил его) или новое очищенное значение. -
Метод
clean()
подкласса формы может выполнять валидацию, требующую доступа к нескольким полям формы. Сюда можно отнести такие проверки, как «если полеA
предоставлено, то полеB
должно содержать действительный адрес электронной почты». При желании этот метод может вернуть совершенно другой словарь, который будет использован в качествеcleaned_data
.Поскольку методы валидации полей были запущены к моменту вызова
clean()
, у вас также есть доступ к атрибутуerrors
формы, который содержит все ошибки, возникшие при очистке отдельных полей.Обратите внимание, что любые ошибки, возникающие при переопределении
Form.clean()
, не будут связаны с каким-либо конкретным полем. Они попадают в специальное «поле» (называемое__all__
), к которому вы можете получить доступ через методnon_field_errors()
, если вам это необходимо. Если вы хотите прикрепить ошибки к определенному полю формы, вам нужно вызватьadd_error()
.Также обратите внимание, что существуют особые соображения при переопределении метода
clean()
подклассаModelForm
. (см. ModelForm documentation для получения дополнительной информации)
Эти методы выполняются в указанном выше порядке, по одному полю за раз. То есть, для каждого поля формы (в порядке их объявления в определении формы) выполняется метод Field.clean()
(или его переопределение), затем clean_<fieldname>()
. Наконец, когда эти два метода выполнены для каждого поля, выполняется метод Form.clean()
, или его переопределение, независимо от того, вызвали ли предыдущие методы ошибки.
Примеры каждого из этих методов приведены ниже.
Как уже упоминалось, любой из этих методов может вызвать ошибку ValidationError
. Для любого поля, если метод Field.clean()
вызывает ValidationError
, любой метод очистки, специфичный для данного поля, не вызывается. Однако методы очистки для всех оставшихся полей все равно выполняются.
Поднятие ValidationError
¶
Чтобы сделать сообщения об ошибках гибкими и легко переопределяемыми, примите во внимание следующие рекомендации:
-
Предоставить описательную ошибку
code
конструктору:# Good ValidationError(_('Invalid value'), code='invalid') # Bad ValidationError(_('Invalid value'))
-
Не вставляйте переменные в сообщение; используйте заполнители и аргумент
params
конструктора:# Good ValidationError( _('Invalid value: %(value)s'), params={'value': '42'}, ) # Bad ValidationError(_('Invalid value: %s') % value)
-
Используйте ключи отображения вместо позиционного форматирования. Это позволяет располагать переменные в любом порядке или вообще их не использовать при переписывании сообщения:
# Good ValidationError( _('Invalid value: %(value)s'), params={'value': '42'}, ) # Bad ValidationError( _('Invalid value: %s'), params=('42',), )
-
Оберните сообщение символом
gettext
, чтобы включить перевод:# Good ValidationError(_('Invalid value')) # Bad ValidationError('Invalid value')
Собираем все вместе:
raise ValidationError( _('Invalid value: %(value)s'), code='invalid', params={'value': '42'}, )
Следование этим рекомендациям особенно необходимо, если вы пишете многократно используемые формы, поля форм и поля моделей.
Хотя это и не рекомендуется, если вы находитесь в конце цепочки валидации (т.е. ваша форма clean()
метод) и вы знаете, что вам никогда не понадобится переопределять сообщение об ошибке, вы можете выбрать менее многословный вариант:
ValidationError(_('Invalid value: %s') % value)
Методы Form.errors.as_data()
и Form.errors.as_json()
значительно выигрывают от полнофункциональных ValidationError
s (с code
именем и params
словарем).
Возникновение множества ошибок¶
Если вы обнаружили несколько ошибок во время работы метода очистки и хотите сигнализировать обо всех из них отправителю формы, можно передать список ошибок конструктору ValidationError
.
Как и выше, рекомендуется передавать список экземпляров ValidationError
с code
s и params
, но подойдет и список строк:
# Good raise ValidationError([ ValidationError(_('Error 1'), code='error1'), ValidationError(_('Error 2'), code='error2'), ]) # Bad raise ValidationError([ _('Error 1'), _('Error 2'), ])
Использование валидации на практике¶
В предыдущих разделах объяснялось, как работает валидация в целом для форм. Поскольку иногда бывает проще понять, как работает каждая функция, здесь приведена серия небольших примеров, в которых используется каждая из предыдущих функций.
Использование валидаторов¶
Поля формы (и модели) Django поддерживают использование полезных функций и классов, известных как валидаторы. Валидатор — это вызываемый объект или функция, которая принимает значение и не возвращает ничего, если значение действительно, или выдает ошибку ValidationError
, если нет. Они могут быть переданы в конструктор поля через аргумент validators
или определены в самом классе Field
с помощью атрибута default_validators
.
Валидаторы могут использоваться для проверки значений внутри поля, давайте посмотрим на Django’s SlugField
:
from django.core import validators from django.forms import CharField class SlugField(CharField): default_validators = [validators.validate_slug]
Как вы можете видеть, SlugField
— это CharField
с настроенным валидатором, который проверяет, что отправленный текст соответствует некоторым правилам символов. Это также можно сделать при определении поля так:
эквивалентно:
slug = forms.CharField(validators=[validators.validate_slug])
Обычные случаи, такие как проверка по электронной почте или регулярному выражению, могут быть обработаны с помощью существующих классов валидаторов, доступных в Django. Например, validators.validate_slug
— это экземпляр RegexValidator
, построенный с первым аргументом в виде шаблона: ^[-a-zA-Z0-9_]+$
. Смотрите раздел writing validators, чтобы увидеть список того, что уже доступно, и пример того, как написать валидатор.
Очистка полей формы по умолчанию¶
Давайте сначала создадим поле пользовательской формы, которое проверяет, что его входные данные — это строка, содержащая адреса электронной почты, разделенные запятыми. Полный класс выглядит следующим образом:
from django import forms from django.core.validators import validate_email class MultiEmailField(forms.Field): def to_python(self, value): """Normalize data to a list of strings.""" # Return an empty list if no input was given. if not value: return [] return value.split(',') def validate(self, value): """Check if value consists only of valid emails.""" # Use the parent's handling of required fields, etc. super().validate(value) for email in value: validate_email(email)
В каждой форме, использующей это поле, эти методы будут выполняться до того, как с данными поля можно будет сделать что-либо еще. Это очистка, специфичная для данного типа поля, независимо от того, как оно будет использоваться в дальнейшем.
Давайте создадим ContactForm
, чтобы продемонстрировать, как вы будете использовать это поле:
class ContactForm(forms.Form): subject = forms.CharField(max_length=100) message = forms.CharField() sender = forms.EmailField() recipients = MultiEmailField() cc_myself = forms.BooleanField(required=False)
Используйте MultiEmailField
как любое другое поле формы. Когда на форме будет вызван метод is_valid()
, в процессе очистки будет запущен метод MultiEmailField.clean()
, который, в свою очередь, вызовет пользовательские методы to_python()
и validate()
.
Очистка определенного атрибута поля¶
Продолжая предыдущий пример, предположим, что в нашем ContactForm
мы хотим убедиться, что поле recipients
всегда содержит адрес "fred@example.com"
. Это проверка, специфичная для нашей формы, поэтому мы не хотим помещать ее в общий класс MultiEmailField
. Вместо этого мы напишем метод очистки, который работает с полем recipients
, следующим образом:
from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean_recipients(self): data = self.cleaned_data['recipients'] if "fred@example.com" not in data: raise ValidationError("You have forgotten about Fred!") # Always return a value to use as the new cleaned data, even if # this method didn't change it. return data
Очистка и проверка полей, которые зависят друг от друга¶
Предположим, мы добавим еще одно требование к нашей контактной форме: если поле cc_myself
является True
, то subject
должно содержать слово "help"
. Мы выполняем проверку более чем одного поля одновременно, поэтому метод формы clean()
является хорошим местом для этого. Обратите внимание, что здесь мы говорим о методе clean()
на форме, тогда как ранее мы писали метод clean()
на поле. Важно четко различать поля и формы, когда мы решаем, где проводить валидацию. Поля — это отдельные точки данных, а формы — это набор полей.
К моменту вызова метода clean()
формы будут запущены все методы очистки отдельных полей (предыдущие два раздела), поэтому self.cleaned_data
будет заполнен любыми данными, которые сохранились до сих пор. Поэтому вам также нужно помнить о том, что поля, которые вы хотите проверить, могут не выдержать первоначальной проверки отдельных полей.
Есть два способа сообщить о любых ошибках на этом этапе. Вероятно, самый распространенный способ — вывести ошибку в верхней части формы. Чтобы создать такую ошибку, вы можете поднять ValidationError
из метода clean()
. Например:
from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() cc_myself = cleaned_data.get("cc_myself") subject = cleaned_data.get("subject") if cc_myself and subject: # Only do something if both fields are valid so far. if "help" not in subject: raise ValidationError( "Did not send for 'help' in the subject despite " "CC'ing yourself." )
В этом коде, если возникает ошибка валидации, форма выводит сообщение об ошибке в верхней части формы (обычно) с описанием проблемы. Такие ошибки являются не-полевыми ошибками, которые отображаются в шаблоне с помощью {{ form.non_field_errors }}
.
Вызов super().clean()
в коде примера гарантирует, что любая логика валидации в родительских классах будет сохранена. Если ваша форма наследует другую, которая не возвращает словарь cleaned_data
в своем методе clean()
(это необязательно), то не присваивайте cleaned_data
результату вызова super()
и используйте self.cleaned_data
вместо этого:
def clean(self): super().clean() cc_myself = self.cleaned_data.get("cc_myself") ...
Второй подход для сообщения об ошибках валидации может включать присвоение сообщения об ошибке одному из полей. В данном случае давайте присвоим сообщение об ошибке обеим строкам «subject» и «cc_myself» в отображении формы. Будьте осторожны, делая это на практике, так как это может привести к запутанному выводу формы. Мы показываем, что здесь возможно, и предоставляем вам и вашим дизайнерам самим решать, что будет эффективно работать в вашей конкретной ситуации. Наш новый код (заменяющий предыдущий пример) выглядит следующим образом:
from django import forms class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() cc_myself = cleaned_data.get("cc_myself") subject = cleaned_data.get("subject") if cc_myself and subject and "help" not in subject: msg = "Must put 'help' in subject when cc'ing yourself." self.add_error('cc_myself', msg) self.add_error('subject', msg)
Вторым аргументом add_error()
может быть строка или, предпочтительно, экземпляр ValidationError
. Более подробную информацию смотрите в Поднятие ValidationError. Обратите внимание, что add_error()
автоматически удаляет поле из cleaned_data
.
The Forms API¶
Bound and unbound forms¶
A Form
instance is either bound to a set of data, or unbound.
-
If it’s bound to a set of data, it’s capable of validating that data
and rendering the form as HTML with the data displayed in the HTML. -
If it’s unbound, it cannot do validation (because there’s no data to
validate!), but it can still render the blank form as HTML.
- class Form¶
To create an unbound Form
instance, instantiate the class:
To bind data to a form, pass the data as a dictionary as the first parameter to
your Form
class constructor:
>>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... } >>> f = ContactForm(data)
In this dictionary, the keys are the field names, which correspond to the
attributes in your Form
class. The values are the data you’re trying to
validate. These will usually be strings, but there’s no requirement that they be
strings; the type of data you pass depends on the Field
, as we’ll see
in a moment.
- Form.is_bound¶
If you need to distinguish between bound and unbound form instances at runtime,
check the value of the form’s is_bound
attribute:
>>> f = ContactForm() >>> f.is_bound False >>> f = ContactForm({"subject": "hello"}) >>> f.is_bound True
Note that passing an empty dictionary creates a bound form with empty data:
>>> f = ContactForm({}) >>> f.is_bound True
If you have a bound Form
instance and want to change the data somehow,
or if you want to bind an unbound Form
instance to some data, create
another Form
instance. There is no way to change data in a
Form
instance. Once a Form
instance has been created, you
should consider its data immutable, whether it has data or not.
Using forms to validate data¶
- Form.clean()¶
Implement a clean()
method on your Form
when you must add custom
validation for fields that are interdependent. See
Cleaning and validating fields that depend on each other for example usage.
- Form.is_valid()¶
The primary task of a Form
object is to validate data. With a bound
Form
instance, call the is_valid()
method to run validation
and return a boolean designating whether the data was valid:
>>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... } >>> f = ContactForm(data) >>> f.is_valid() True
Let’s try with some invalid data. In this case, subject
is blank (an error,
because all fields are required by default) and sender
is not a valid
email address:
>>> data = { ... "subject": "", ... "message": "Hi there", ... "sender": "invalid email address", ... "cc_myself": True, ... } >>> f = ContactForm(data) >>> f.is_valid() False
- Form.errors¶
Access the errors
attribute to get a dictionary of error
messages:
>>> f.errors {'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}
In this dictionary, the keys are the field names, and the values are lists of
strings representing the error messages. The error messages are stored
in lists because a field can have multiple error messages.
You can access errors
without having to call
is_valid()
first. The form’s data will be validated the first time
either you call is_valid()
or access errors
.
The validation routines will only get called once, regardless of how many times
you access errors
or call is_valid()
. This means that
if validation has side effects, those side effects will only be triggered once.
- Form.errors.as_data()¶
Returns a dict
that maps fields to their original ValidationError
instances.
>>> f.errors.as_data() {'sender': [ValidationError(['Enter a valid email address.'])], 'subject': [ValidationError(['This field is required.'])]}
Use this method anytime you need to identify an error by its code
. This
enables things like rewriting the error’s message or writing custom logic in a
view when a given error is present. It can also be used to serialize the errors
in a custom format (e.g. XML); for instance, as_json()
relies on as_data()
.
The need for the as_data()
method is due to backwards compatibility.
Previously ValidationError
instances were lost as soon as their
rendered error messages were added to the Form.errors
dictionary.
Ideally Form.errors
would have stored ValidationError
instances
and methods with an as_
prefix could render them, but it had to be done
the other way around in order not to break code that expects rendered error
messages in Form.errors
.
- Form.errors.as_json(escape_html=False)¶
Returns the errors serialized as JSON.
>>> f.errors.as_json() {"sender": [{"message": "Enter a valid email address.", "code": "invalid"}], "subject": [{"message": "This field is required.", "code": "required"}]}
By default, as_json()
does not escape its output. If you are using it for
something like AJAX requests to a form view where the client interprets the
response and inserts errors into the page, you’ll want to be sure to escape the
results on the client-side to avoid the possibility of a cross-site scripting
attack. You can do this in JavaScript with element.textContent = errorText
or with jQuery’s $(el).text(errorText)
(rather than its .html()
function).
If for some reason you don’t want to use client-side escaping, you can also
set escape_html=True
and error messages will be escaped so you can use them
directly in HTML.
- Form.errors.get_json_data(escape_html=False)¶
Returns the errors as a dictionary suitable for serializing to JSON.
Form.errors.as_json()
returns serialized JSON, while this returns the
error data before it’s serialized.
The escape_html
parameter behaves as described in
Form.errors.as_json()
.
- Form.add_error(field, error)¶
This method allows adding errors to specific fields from within the
Form.clean()
method, or from outside the form altogether; for instance
from a view.
The field
argument is the name of the field to which the errors
should be added. If its value is None
the error will be treated as
a non-field error as returned by Form.non_field_errors()
.
The error
argument can be a string, or preferably an instance of
ValidationError
. See Raising ValidationError for best practices
when defining form errors.
Note that Form.add_error()
automatically removes the relevant field from
cleaned_data
.
- Form.has_error(field, code=None)¶
This method returns a boolean designating whether a field has an error with
a specific error code
. If code
is None
, it will return True
if the field contains any errors at all.
To check for non-field errors use
NON_FIELD_ERRORS
as the field
parameter.
- Form.non_field_errors()¶
This method returns the list of errors from Form.errors
that aren’t associated with a particular field.
This includes ValidationError
s that are raised in Form.clean()
and errors added using Form.add_error(None,
.
"...")
Behavior of unbound forms¶
It’s meaningless to validate a form with no data, but, for the record, here’s
what happens with unbound forms:
>>> f = ContactForm() >>> f.is_valid() False >>> f.errors {}
Initial form values¶
- Form.initial¶
Use initial
to declare the initial value of form fields at
runtime. For example, you might want to fill in a username
field with the
username of the current session.
To accomplish this, use the initial
argument to a Form
.
This argument, if given, should be a dictionary mapping field names to initial
values. Only include the fields for which you’re specifying an initial value;
it’s not necessary to include every field in your form. For example:
>>> f = ContactForm(initial={"subject": "Hi there!"})
These values are only displayed for unbound forms, and they’re not used as
fallback values if a particular value isn’t provided.
If a Field
defines initial
and you
include initial
when instantiating the Form
, then the latter
initial
will have precedence. In this example, initial
is provided both
at the field level and at the form instance level, and the latter gets
precedence:
>>> from django import forms >>> class CommentForm(forms.Form): ... name = forms.CharField(initial="class") ... url = forms.URLField() ... comment = forms.CharField() ... >>> f = CommentForm(initial={"name": "instance"}, auto_id=False) >>> print(f) <tr><th>Name:</th><td><input type="text" name="name" value="instance" required></td></tr> <tr><th>Url:</th><td><input type="url" name="url" required></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>
- Form.get_initial_for_field(field, field_name)¶
Returns the initial data for a form field. It retrieves the data from
Form.initial
if present, otherwise trying Field.initial
.
Callable values are evaluated.
It is recommended to use BoundField.initial
over
get_initial_for_field()
because BoundField.initial
has a
simpler interface. Also, unlike get_initial_for_field()
,
BoundField.initial
caches its values. This is useful especially when
dealing with callables whose return values can change (e.g. datetime.now
or
uuid.uuid4
):
>>> import uuid >>> class UUIDCommentForm(CommentForm): ... identifier = forms.UUIDField(initial=uuid.uuid4) ... >>> f = UUIDCommentForm() >>> f.get_initial_for_field(f.fields["identifier"], "identifier") UUID('972ca9e4-7bfe-4f5b-af7d-07b3aa306334') >>> f.get_initial_for_field(f.fields["identifier"], "identifier") UUID('1b411fab-844e-4dec-bd4f-e9b0495f04d0') >>> # Using BoundField.initial, for comparison >>> f["identifier"].initial UUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30') >>> f["identifier"].initial UUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')
Checking which form data has changed¶
- Form.has_changed()¶
Use the has_changed()
method on your Form
when you need to check if the
form data has been changed from the initial data.
>>> data = {'subject': 'hello', ... 'message': 'Hi there', ... 'sender': 'foo@example.com', ... 'cc_myself': True} >>> f = ContactForm(data, initial=data) >>> f.has_changed() False
When the form is submitted, we reconstruct it and provide the original data
so that the comparison can be done:
>>> f = ContactForm(request.POST, initial=data) >>> f.has_changed()
has_changed()
will be True
if the data from request.POST
differs
from what was provided in initial
or False
otherwise. The
result is computed by calling Field.has_changed()
for each field in the
form.
- Form.changed_data¶
The changed_data
attribute returns a list of the names of the fields whose
values in the form’s bound data (usually request.POST
) differ from what was
provided in initial
. It returns an empty list if no data differs.
>>> f = ContactForm(request.POST, initial=data) >>> if f.has_changed(): ... print("The following fields changed: %s" % ", ".join(f.changed_data)) >>> f.changed_data ['subject', 'message']
Accessing the fields from the form¶
- Form.fields¶
You can access the fields of Form
instance from its fields
attribute:
>>> for row in f.fields.values(): ... print(row) ... <django.forms.fields.CharField object at 0x7ffaac632510> <django.forms.fields.URLField object at 0x7ffaac632f90> <django.forms.fields.CharField object at 0x7ffaac3aa050> >>> f.fields["name"] <django.forms.fields.CharField object at 0x7ffaac6324d0>
You can alter the field and BoundField
of Form
instance to
change the way it is presented in the form:
>>> f.as_div().split("</div>")[0] '<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject">' >>> f["subject"].label = "Topic" >>> f.as_div().split("</div>")[0] '<div><label for="id_subject">Topic:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'
Beware not to alter the base_fields
attribute because this modification
will influence all subsequent ContactForm
instances within the same Python
process:
>>> f.base_fields["subject"].label_suffix = "?" >>> another_f = CommentForm(auto_id=False) >>> f.as_div().split("</div>")[0] '<div><label for="id_subject">Subject?</label><input type="text" name="subject" maxlength="100" required id="id_subject">'
Accessing “clean” data¶
- Form.cleaned_data¶
Each field in a Form
class is responsible not only for validating
data, but also for “cleaning” it – normalizing it to a consistent format. This
is a nice feature, because it allows data for a particular field to be input in
a variety of ways, always resulting in consistent output.
For example, DateField
normalizes input into a
Python datetime.date
object. Regardless of whether you pass it a string in
the format '1994-07-15'
, a datetime.date
object, or a number of other
formats, DateField
will always normalize it to a datetime.date
object
as long as it’s valid.
Once you’ve created a Form
instance with a set of data and validated
it, you can access the clean data via its cleaned_data
attribute:
>>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... } >>> f = ContactForm(data) >>> f.is_valid() True >>> f.cleaned_data {'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}
Note that any text-based field – such as CharField
or EmailField
–
always cleans the input into a string. We’ll cover the encoding implications
later in this document.
If your data does not validate, the cleaned_data
dictionary contains
only the valid fields:
>>> data = { ... "subject": "", ... "message": "Hi there", ... "sender": "invalid email address", ... "cc_myself": True, ... } >>> f = ContactForm(data) >>> f.is_valid() False >>> f.cleaned_data {'cc_myself': True, 'message': 'Hi there'}
cleaned_data
will always only contain a key for fields defined in the
Form
, even if you pass extra data when you define the Form
. In this
example, we pass a bunch of extra fields to the ContactForm
constructor,
but cleaned_data
contains only the form’s fields:
>>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... "extra_field_1": "foo", ... "extra_field_2": "bar", ... "extra_field_3": "baz", ... } >>> f = ContactForm(data) >>> f.is_valid() True >>> f.cleaned_data # Doesn't contain extra_field_1, etc. {'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}
When the Form
is valid, cleaned_data
will include a key and value for
all its fields, even if the data didn’t include a value for some optional
fields. In this example, the data dictionary doesn’t include a value for the
nick_name
field, but cleaned_data
includes it, with an empty value:
>>> from django import forms >>> class OptionalPersonForm(forms.Form): ... first_name = forms.CharField() ... last_name = forms.CharField() ... nick_name = forms.CharField(required=False) ... >>> data = {"first_name": "John", "last_name": "Lennon"} >>> f = OptionalPersonForm(data) >>> f.is_valid() True >>> f.cleaned_data {'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}
In this above example, the cleaned_data
value for nick_name
is set to an
empty string, because nick_name
is CharField
, and CharField
s treat
empty values as an empty string. Each field type knows what its “blank” value
is – e.g., for DateField
, it’s None
instead of the empty string. For
full details on each field’s behavior in this case, see the “Empty value” note
for each field in the “Built-in Field
classes” section below.
You can write code to perform validation for particular form fields (based on
their name) or for the form as a whole (considering combinations of various
fields). More information about this is in Form and field validation.
Outputting forms as HTML¶
The second task of a Form
object is to render itself as HTML. To do so,
print
it:
>>> f = ContactForm() >>> print(f) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr> <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>
If the form is bound to data, the HTML output will include that data
appropriately. For example, if a field is represented by an
<input type="text">
, the data will be in the value
attribute. If a
field is represented by an <input type="checkbox">
, then that HTML will
include checked
if appropriate:
>>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... } >>> f = ContactForm(data) >>> print(f) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" required></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" required></td></tr> <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="foo@example.com" required></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked></td></tr>
This default output is a two-column HTML table, with a <tr>
for each field.
Notice the following:
-
For flexibility, the output does not include the
<table>
and
</table>
tags, nor does it include the<form>
and</form>
tags or an<input type="submit">
tag. It’s your job to do that. -
Each field type has a default HTML representation.
CharField
is
represented by an<input type="text">
andEmailField
by an
<input type="email">
.BooleanField(null=False)
is represented by an
<input type="checkbox">
. Note these are merely sensible defaults; you can
specify which HTML to use for a given field by using widgets, which we’ll
explain shortly. -
The HTML
name
for each tag is taken directly from its attribute name
in theContactForm
class. -
The text label for each field – e.g.
'Subject:'
,'Message:'
and
'Cc myself:'
is generated from the field name by converting all
underscores to spaces and upper-casing the first letter. Again, note
these are merely sensible defaults; you can also specify labels manually. -
Each text label is surrounded in an HTML
<label>
tag, which points
to the appropriate form field via itsid
. Itsid
, in turn, is
generated by prepending'id_'
to the field name. Theid
attributes and<label>
tags are included in the output by default, to
follow best practices, but you can change that behavior. -
The output uses HTML5 syntax, targeting
<!DOCTYPE html>
. For example,
it uses boolean attributes such aschecked
rather than the XHTML style
ofchecked='checked'
.
Although <table>
output is the default output style when you print
a
form, other output styles are available. Each style is available as a method on
a form object, and each rendering method returns a string.
Default rendering¶
The default rendering when you print
a form uses the following methods and
attributes.
template_name
¶
- Form.template_name¶
The name of the template rendered if the form is cast into a string, e.g. via
print(form)
or in a template via {{ form }}
.
By default, a property returning the value of the renderer’s
form_template_name
. You may set it
as a string template name in order to override that for a particular form
class.
In older versions template_name
defaulted to the string value
'django/forms/default.html'
.
render()
¶
- Form.render(template_name=None, context=None, renderer=None)¶
The render method is called by __str__
as well as the
Form.as_table()
, Form.as_p()
, and Form.as_ul()
methods.
All arguments are optional and default to:
-
template_name
:Form.template_name
-
context
: Value returned byForm.get_context()
-
renderer
: Value returned byForm.default_renderer
By passing template_name
you can customize the template used for just a
single call.
get_context()
¶
- Form.get_context()¶
Return the template context for rendering the form.
The available context is:
-
form
: The bound form. -
fields
: All bound fields, except the hidden fields. -
hidden_fields
: All hidden bound fields. -
errors
: All non field related or hidden field related form errors.
template_name_label
¶
- Form.template_name_label¶
The template used to render a field’s <label>
, used when calling
BoundField.label_tag()
/legend_tag()
. Can be changed per
form by overriding this attribute or more generally by overriding the default
template, see also Overriding built-in form templates.
Output styles¶
As well as rendering the form directly, such as in a template with
{{ form }}
, the following helper functions serve as a proxy to
Form.render()
passing a particular template_name
value.
These helpers are most useful in a template, where you need to override the
form renderer or form provided value but cannot pass the additional parameter
to render()
. For example, you can render a form as an unordered
list using {{ form.as_ul }}
.
Each helper pairs a form method with an attribute giving the appropriate
template name.
as_div()
¶
- Form.template_name_div¶
The template used by as_div()
. Default: 'django/forms/div.html'
.
- Form.as_div()¶
as_div()
renders the form as a series of <div>
elements, with each
<div>
containing one field, such as:
>>> f = ContactForm() >>> f.as_div()
… gives HTML like:
<div> <label for="id_subject">Subject:</label> <input type="text" name="subject" maxlength="100" required id="id_subject"> </div> <div> <label for="id_message">Message:</label> <input type="text" name="message" required id="id_message"> </div> <div> <label for="id_sender">Sender:</label> <input type="email" name="sender" required id="id_sender"> </div> <div> <label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"> </div>
Note
Of the framework provided templates and output styles, as_div()
is
recommended over the as_p()
, as_table()
, and as_ul()
versions
as the template implements <fieldset>
and <legend>
to group related
inputs and is easier for screen reader users to navigate.
as_p()
¶
- Form.template_name_p¶
The template used by as_p()
. Default: 'django/forms/p.html'
.
- Form.as_p()¶
as_p()
renders the form as a series of <p>
tags, with each <p>
containing one field:
>>> f = ContactForm() >>> f.as_p() '<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p>n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p>n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required></p>n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>' >>> print(f.as_p()) <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p> <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p> <p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></p> <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>
as_ul()
¶
- Form.template_name_ul¶
The template used by as_ul()
. Default: 'django/forms/ul.html'
.
- Form.as_ul()¶
as_ul()
renders the form as a series of <li>
tags, with each <li>
containing one field. It does not include the <ul>
or </ul>
, so that
you can specify any HTML attributes on the <ul>
for flexibility:
>>> f = ContactForm() >>> f.as_ul() '<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li>n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li>n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li>n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>' >>> print(f.as_ul()) <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li> <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li> <li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li> <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>
as_table()
¶
- Form.template_name_table¶
The template used by as_table()
. Default: 'django/forms/table.html'
.
- Form.as_table()¶
as_table()
renders the form as an HTML <table>
:
>>> f = ContactForm() >>> f.as_table() '<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>' >>> print(f) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr> <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>
Styling required or erroneous form rows¶
- Form.error_css_class¶
- Form.required_css_class¶
It’s pretty common to style form rows and fields that are required or have
errors. For example, you might want to present required form rows in bold and
highlight errors in red.
The Form
class has a couple of hooks you can use to add class
attributes to required rows or to rows with errors: set the
Form.error_css_class
and/or Form.required_css_class
attributes:
from django import forms class ContactForm(forms.Form): error_css_class = "error" required_css_class = "required" # ... and the rest of your fields here
Once you’ve done that, rows will be given "error"
and/or "required"
classes, as needed. The HTML will look something like:
>>> f = ContactForm(data) >>> print(f.as_table()) <tr class="required"><th><label class="required" for="id_subject">Subject:</label> ... <tr class="required"><th><label class="required" for="id_message">Message:</label> ... <tr class="required error"><th><label class="required" for="id_sender">Sender:</label> ... <tr><th><label for="id_cc_myself">Cc myself:<label> ... >>> f["subject"].label_tag() <label class="required" for="id_subject">Subject:</label> >>> f["subject"].legend_tag() <legend class="required" for="id_subject">Subject:</legend> >>> f["subject"].label_tag(attrs={"class": "foo"}) <label for="id_subject" class="foo required">Subject:</label> >>> f["subject"].legend_tag(attrs={"class": "foo"}) <legend for="id_subject" class="foo required">Subject:</legend>
Configuring form elements’ HTML id
attributes and <label>
tags¶
- Form.auto_id¶
By default, the form rendering methods include:
-
HTML
id
attributes on the form elements. -
The corresponding
<label>
tags around the labels. An HTML<label>
tag
designates which label text is associated with which form element. This small
enhancement makes forms more usable and more accessible to assistive devices.
It’s always a good idea to use<label>
tags.
The id
attribute values are generated by prepending id_
to the form
field names. This behavior is configurable, though, if you want to change the
id
convention or remove HTML id
attributes and <label>
tags
entirely.
Use the auto_id
argument to the Form
constructor to control the id
and label behavior. This argument must be True
, False
or a string.
If auto_id
is False
, then the form output will not include <label>
tags nor id
attributes:
>>> f = ContactForm(auto_id=False) >>> print(f.as_div()) <div>Subject:<input type="text" name="subject" maxlength="100" required></div> <div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div> <div>Sender:<input type="email" name="sender" required></div> <div>Cc myself:<input type="checkbox" name="cc_myself"></div>
If auto_id
is set to True
, then the form output will include
<label>
tags and will use the field name as its id
for each form
field:
>>> f = ContactForm(auto_id=True) >>> print(f.as_div()) <div><label for="subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="subject"></div> <div><label for="message">Message:</label><textarea name="message" cols="40" rows="10" required id="message"></textarea></div> <div><label for="sender">Sender:</label><input type="email" name="sender" required id="sender"></div> <div><label for="cc_myself">Cc myself:</label><input type="checkbox" name="cc_myself" id="cc_myself"></div>
If auto_id
is set to a string containing the format character '%s'
,
then the form output will include <label>
tags, and will generate id
attributes based on the format string. For example, for a format string
'field_%s'
, a field named subject
will get the id
value
'field_subject'
. Continuing our example:
>>> f = ContactForm(auto_id="id_for_%s") >>> print(f.as_div()) <div><label for="id_for_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div> <div><label for="id_for_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div> <div><label for="id_for_sender">Sender:</label><input type="email" name="sender" required id="id_for_sender"></div> <div><label for="id_for_cc_myself">Cc myself:</label><input type="checkbox" name="cc_myself" id="id_for_cc_myself"></div>
If auto_id
is set to any other true value – such as a string that doesn’t
include %s
– then the library will act as if auto_id
is True
.
By default, auto_id
is set to the string 'id_%s'
.
- Form.label_suffix¶
A translatable string (defaults to a colon (:
) in English) that will be
appended after any label name when a form is rendered.
It’s possible to customize that character, or omit it entirely, using the
label_suffix
parameter:
>>> f = ContactForm(auto_id="id_for_%s", label_suffix="") >>> print(f.as_div()) <div><label for="id_for_subject">Subject</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div> <div><label for="id_for_message">Message</label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div> <div><label for="id_for_sender">Sender</label><input type="email" name="sender" required id="id_for_sender"></div> <div><label for="id_for_cc_myself">Cc myself</label><input type="checkbox" name="cc_myself" id="id_for_cc_myself"></div> >>> f = ContactForm(auto_id="id_for_%s", label_suffix=" ->") >>> print(f.as_div()) <div><label for="id_for_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div> <div><label for="id_for_message">Message -></label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div> <div><label for="id_for_sender">Sender -></label><input type="email" name="sender" required id="id_for_sender"></div> <div><label for="id_for_cc_myself">Cc myself -></label><input type="checkbox" name="cc_myself" id="id_for_cc_myself"></div>
Note that the label suffix is added only if the last character of the
label isn’t a punctuation character (in English, those are .
, !
, ?
or :
).
Fields can also define their own label_suffix
.
This will take precedence over Form.label_suffix
. The suffix can also be overridden at runtime
using the label_suffix
parameter to
label_tag()
/
legend_tag()
.
- Form.use_required_attribute¶
When set to True
(the default), required form fields will have the
required
HTML attribute.
Formsets instantiate forms with
use_required_attribute=False
to avoid incorrect browser validation when
adding and deleting forms from a formset.
Configuring the rendering of a form’s widgets¶
- Form.default_renderer¶
Specifies the renderer to use for the form. Defaults to
None
which means to use the default renderer specified by the
FORM_RENDERER
setting.
You can set this as a class attribute when declaring your form or use the
renderer
argument to Form.__init__()
. For example:
from django import forms class MyForm(forms.Form): default_renderer = MyRenderer()
or:
form = MyForm(renderer=MyRenderer())
Notes on field ordering¶
In the as_p()
, as_ul()
and as_table()
shortcuts, the fields are
displayed in the order in which you define them in your form class. For
example, in the ContactForm
example, the fields are defined in the order
subject
, message
, sender
, cc_myself
. To reorder the HTML
output, change the order in which those fields are listed in the class.
There are several other ways to customize the order:
- Form.field_order¶
By default Form.field_order=None
, which retains the order in which you
define the fields in your form class. If field_order
is a list of field
names, the fields are ordered as specified by the list and remaining fields are
appended according to the default order. Unknown field names in the list are
ignored. This makes it possible to disable a field in a subclass by setting it
to None
without having to redefine ordering.
You can also use the Form.field_order
argument to a Form
to
override the field order. If a Form
defines
field_order
and you include field_order
when instantiating
the Form
, then the latter field_order
will have precedence.
- Form.order_fields(field_order)¶
You may rearrange the fields any time using order_fields()
with a list of
field names as in field_order
.
How errors are displayed¶
If you render a bound Form
object, the act of rendering will automatically
run the form’s validation if it hasn’t already happened, and the HTML output
will include the validation errors as a <ul class="errorlist">
near the
field. The particular positioning of the error messages depends on the output
method you’re using:
>>> data = { ... "subject": "", ... "message": "Hi there", ... "sender": "invalid email address", ... "cc_myself": True, ... } >>> f = ContactForm(data, auto_id=False) >>> print(f.as_div()) <div>Subject:<ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" required></div> <div>Message:<textarea name="message" cols="40" rows="10" required>Hi there</textarea></div> <div>Sender:<ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" required></div> <div>Cc myself:<input type="checkbox" name="cc_myself" checked></div> >>> print(f.as_table()) <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" required></td></tr> <tr><th>Message:</th><td><textarea name="message" cols="40" rows="10" required></textarea></td></tr> <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" required></td></tr> <tr><th>Cc myself:</th><td><input checked type="checkbox" name="cc_myself"></td></tr> >>> print(f.as_ul()) <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" required></li> <li>Message: <textarea name="message" cols="40" rows="10" required></textarea></li> <li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="email" name="sender" value="invalid email address" required></li> <li>Cc myself: <input checked type="checkbox" name="cc_myself"></li> >>> print(f.as_p()) <p><ul class="errorlist"><li>This field is required.</li></ul></p> <p>Subject: <input type="text" name="subject" maxlength="100" required></p> <p>Message: <textarea name="message" cols="40" rows="10" required></textarea></p> <p><ul class="errorlist"><li>Enter a valid email address.</li></ul></p> <p>Sender: <input type="email" name="sender" value="invalid email address" required></p> <p>Cc myself: <input checked type="checkbox" name="cc_myself"></p>
Customizing the error list format¶
- class ErrorList(initlist=None, error_class=None, renderer=None)¶
-
By default, forms use
django.forms.utils.ErrorList
to format validation
errors.ErrorList
is a list like object whereinitlist
is the
list of errors. In addition this class has the following attributes and
methods.- error_class¶
-
The CSS classes to be used when rendering the error list. Any provided
classes are added to the defaulterrorlist
class.
- renderer¶
-
Specifies the renderer to use for
ErrorList
.
Defaults toNone
which means to use the default renderer
specified by theFORM_RENDERER
setting.
- template_name¶
-
The name of the template used when calling
__str__
or
render()
. By default this is
'django/forms/errors/list/default.html'
which is a proxy for the
'ul.html'
template.
- template_name_text¶
-
The name of the template used when calling
as_text()
. By default
this is'django/forms/errors/list/text.html'
. This template renders
the errors as a list of bullet points.
- template_name_ul¶
-
The name of the template used when calling
as_ul()
. By default
this is'django/forms/errors/list/ul.html'
. This template renders
the errors in<li>
tags with a wrapping<ul>
with the CSS
classes as defined byerror_class
.
- get_context()¶
-
Return context for rendering of errors in a template.
The available context is:
-
errors
: A list of the errors. -
error_class
: A string of CSS classes.
-
- render(template_name=None, context=None, renderer=None)¶
-
The render method is called by
__str__
as well as by the
as_ul()
method.All arguments are optional and will default to:
-
template_name
: Value returned bytemplate_name
-
context
: Value returned byget_context()
-
renderer
: Value returned byrenderer
-
- as_text()¶
-
Renders the error list using the template defined by
template_name_text
.
- as_ul()¶
-
Renders the error list using the template defined by
template_name_ul
.
If you’d like to customize the rendering of errors this can be achieved by
overriding thetemplate_name
attribute or more generally by
overriding the default template, see also
Overriding built-in form templates.
Deprecated since version 4.0: The ability to return a str
when calling the __str__
method is
deprecated. Use the template engine instead which returns a SafeString
.
More granular output¶
The as_p()
, as_ul()
, and as_table()
methods are shortcuts –
they’re not the only way a form object can be displayed.
- class BoundField¶
-
Used to display HTML or access attributes for a single field of a
Form
instance.The
__str__()
method of this object displays the HTML for this field.
To retrieve a single BoundField
, use dictionary lookup syntax on your form
using the field’s name as the key:
>>> form = ContactForm() >>> print(form["subject"]) <input id="id_subject" type="text" name="subject" maxlength="100" required>
To retrieve all BoundField
objects, iterate the form:
>>> form = ContactForm() >>> for boundfield in form: ... print(boundfield) ... <input id="id_subject" type="text" name="subject" maxlength="100" required> <input type="text" name="message" id="id_message" required> <input type="email" name="sender" id="id_sender" required> <input type="checkbox" name="cc_myself" id="id_cc_myself">
The field-specific output honors the form object’s auto_id
setting:
>>> f = ContactForm(auto_id=False) >>> print(f["message"]) <input type="text" name="message" required> >>> f = ContactForm(auto_id="id_%s") >>> print(f["message"]) <input type="text" name="message" id="id_message" required>
Attributes of BoundField
¶
- BoundField.auto_id¶
-
The HTML ID attribute for this
BoundField
. Returns an empty string
ifForm.auto_id
isFalse
.
- BoundField.data¶
-
This property returns the data for this
BoundField
extracted by the widget’svalue_from_datadict()
method, orNone
if it wasn’t given:>>> unbound_form = ContactForm() >>> print(unbound_form["subject"].data) None >>> bound_form = ContactForm(data={"subject": "My Subject"}) >>> print(bound_form["subject"].data) My Subject
- BoundField.errors¶
-
A list-like object that is displayed
as an HTML<ul class="errorlist">
when printed:>>> data = {"subject": "hi", "message": "", "sender": "", "cc_myself": ""} >>> f = ContactForm(data, auto_id=False) >>> print(f["message"]) <input type="text" name="message" required> >>> f["message"].errors ['This field is required.'] >>> print(f["message"].errors) <ul class="errorlist"><li>This field is required.</li></ul> >>> f["subject"].errors [] >>> print(f["subject"].errors) >>> str(f["subject"].errors) ''
- BoundField.field¶
-
The form
Field
instance from the form class that
thisBoundField
wraps.
- BoundField.form¶
-
The
Form
instance thisBoundField
is bound to.
- BoundField.help_text¶
-
The
help_text
of the field.
- BoundField.html_name¶
-
The name that will be used in the widget’s HTML
name
attribute. It takes
the formprefix
into account.
- BoundField.id_for_label¶
-
Use this property to render the ID of this field. For example, if you are
manually constructing a<label>
in your template (despite the fact that
label_tag()
/legend_tag()
will do this
for you):<label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}
By default, this will be the field’s name prefixed by
id_
(”id_my_field
” for the example above). You may modify the ID by setting
attrs
on the field’s widget. For example,
declaring a field like this:my_field = forms.CharField(widget=forms.TextInput(attrs={"id": "myFIELD"}))
and using the template above, would render something like:
<label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" required>
- BoundField.initial¶
-
Use
BoundField.initial
to retrieve initial data for a form field.
It retrieves the data fromForm.initial
if present, otherwise
tryingField.initial
. Callable values are evaluated. See
Initial form values for more examples.BoundField.initial
caches its return value, which is useful
especially when dealing with callables whose return values can change (e.g.
datetime.now
oruuid.uuid4
):>>> from datetime import datetime >>> class DatedCommentForm(CommentForm): ... created = forms.DateTimeField(initial=datetime.now) ... >>> f = DatedCommentForm() >>> f["created"].initial datetime.datetime(2021, 7, 27, 9, 5, 54) >>> f["created"].initial datetime.datetime(2021, 7, 27, 9, 5, 54)
Using
BoundField.initial
is recommended over
get_initial_for_field()
.
- BoundField.is_hidden¶
-
Returns
True
if thisBoundField
’s widget is
hidden.
- BoundField.label¶
-
The
label
of the field. This is used in
label_tag()
/legend_tag()
.
- BoundField.name¶
-
The name of this field in the form:
>>> f = ContactForm() >>> print(f["subject"].name) subject >>> print(f["message"].name) message
- BoundField.use_fieldset¶
-
Returns the value of this BoundField widget’s
use_fieldset
attribute.
- BoundField.widget_type¶
-
Returns the lowercased class name of the wrapped field’s widget, with any
trailinginput
orwidget
removed. This may be used when building
forms where the layout is dependent upon the widget type. For example:{% for field in form %} {% if field.widget_type == 'checkbox' %} # render one way {% else %} # render another way {% endif %} {% endfor %}
Methods of BoundField
¶
- BoundField.as_hidden(attrs=None, **kwargs)¶
-
Returns a string of HTML for representing this as an
<input type="hidden">
.**kwargs
are passed toas_widget()
.This method is primarily used internally. You should use a widget instead.
- BoundField.as_widget(widget=None, attrs=None, only_initial=False)¶
-
Renders the field by rendering the passed widget, adding any HTML
attributes passed asattrs
. If no widget is specified, then the
field’s default widget will be used.only_initial
is used by Django internals and should not be set
explicitly.
- BoundField.css_classes(extra_classes=None)¶
-
When you use Django’s rendering shortcuts, CSS classes are used to
indicate required form fields or fields that contain errors. If you’re
manually rendering a form, you can access these CSS classes using the
css_classes
method:>>> f = ContactForm(data={"message": ""}) >>> f["message"].css_classes() 'required'
If you want to provide some additional classes in addition to the
error and required classes that may be required, you can provide
those classes as an argument:>>> f = ContactForm(data={"message": ""}) >>> f["message"].css_classes("foo bar") 'foo bar required'
- BoundField.label_tag(contents=None, attrs=None, label_suffix=None, tag=None)¶
-
Renders a label tag for the form field using the template specified by
Form.template_name_label
.The available context is:
-
field
: This instance of theBoundField
. -
contents
: By default a concatenated string of
BoundField.label
andForm.label_suffix
(or
Field.label_suffix
, if set). This can be overridden by the
contents
andlabel_suffix
arguments. -
attrs
: Adict
containingfor
,
Form.required_css_class
, andid
.id
is generated by the
field’s widgetattrs
orBoundField.auto_id
. Additional
attributes can be provided by theattrs
argument. -
use_tag
: A boolean which isTrue
if the label has anid
.
IfFalse
the default template omits thetag
. -
tag
: An optional string to customize the tag, defaults tolabel
.
Tip
In your template
field
is the instance of theBoundField
.
Thereforefield.field
accessesBoundField.field
being
the field you declare, e.g.forms.CharField
.To separately render the label tag of a form field, you can call its
label_tag()
method:>>> f = ContactForm(data={"message": ""}) >>> print(f["message"].label_tag()) <label for="id_message">Message:</label>
If you’d like to customize the rendering this can be achieved by overriding
theForm.template_name_label
attribute or more generally by
overriding the default template, see also
Overriding built-in form templates.The
tag
argument was added. -
- BoundField.legend_tag(contents=None, attrs=None, label_suffix=None)¶
-
Calls
label_tag()
withtag='legend'
to render the label with
<legend>
tags. This is useful when rendering radio and multiple
checkbox widgets where<legend>
may be more appropriate than a
<label>
.
- BoundField.value()¶
-
Use this method to render the raw value of this field as it would be rendered
by aWidget
:>>> initial = {"subject": "welcome"} >>> unbound_form = ContactForm(initial=initial) >>> bound_form = ContactForm(data={"subject": "hi"}, initial=initial) >>> print(unbound_form["subject"].value()) welcome >>> print(bound_form["subject"].value()) hi
Customizing BoundField
¶
If you need to access some additional information about a form field in a
template and using a subclass of Field
isn’t
sufficient, consider also customizing BoundField
.
A custom form field can override get_bound_field()
:
- Field.get_bound_field(form, field_name)¶
-
Takes an instance of
Form
and the name of the field.
The return value will be used when accessing the field in a template. Most
likely it will be an instance of a subclass of
BoundField
.
If you have a GPSCoordinatesField
, for example, and want to be able to
access additional information about the coordinates in a template, this could
be implemented as follows:
class GPSCoordinatesBoundField(BoundField): @property def country(self): """ Return the country the coordinates lie in or None if it can't be determined. """ value = self.value() if value: return get_country_from_coordinates(value) else: return None class GPSCoordinatesField(Field): def get_bound_field(self, form, field_name): return GPSCoordinatesBoundField(form, self, field_name)
Now you can access the country in a template with
{{ form.coordinates.country }}
.
Binding uploaded files to a form¶
Dealing with forms that have FileField
and ImageField
fields
is a little more complicated than a normal form.
Firstly, in order to upload files, you’ll need to make sure that your
<form>
element correctly defines the enctype
as
"multipart/form-data"
:
<form enctype="multipart/form-data" method="post" action="/foo/">
Secondly, when you use the form, you need to bind the file data. File
data is handled separately to normal form data, so when your form
contains a FileField
and ImageField
, you will need to specify
a second argument when you bind your form. So if we extend our
ContactForm to include an ImageField
called mugshot
, we
need to bind the file data containing the mugshot image:
# Bound form with an image field >>> from django.core.files.uploadedfile import SimpleUploadedFile >>> data = { ... "subject": "hello", ... "message": "Hi there", ... "sender": "foo@example.com", ... "cc_myself": True, ... } >>> file_data = {"mugshot": SimpleUploadedFile("face.jpg", b"file data")} >>> f = ContactFormWithMugshot(data, file_data)
In practice, you will usually specify request.FILES
as the source
of file data (just like you use request.POST
as the source of
form data):
# Bound form with an image field, data from the request >>> f = ContactFormWithMugshot(request.POST, request.FILES)
Constructing an unbound form is the same as always – omit both form data and
file data:
# Unbound form with an image field >>> f = ContactFormWithMugshot()
Testing for multipart forms¶
- Form.is_multipart()¶
If you’re writing reusable views or templates, you may not know ahead of time
whether your form is a multipart form or not. The is_multipart()
method
tells you whether the form requires multipart encoding for submission:
>>> f = ContactFormWithMugshot() >>> f.is_multipart() True
Here’s an example of how you might use this in a template:
{% if form.is_multipart %} <form enctype="multipart/form-data" method="post" action="/foo/"> {% else %} <form method="post" action="/foo/"> {% endif %} {{ form }} </form>
Subclassing forms¶
If you have multiple Form
classes that share fields, you can use
subclassing to remove redundancy.
When you subclass a custom Form
class, the resulting subclass will
include all fields of the parent class(es), followed by the fields you define
in the subclass.
In this example, ContactFormWithPriority
contains all the fields from
ContactForm
, plus an additional field, priority
. The ContactForm
fields are ordered first:
>>> class ContactFormWithPriority(ContactForm): ... priority = forms.CharField() ... >>> f = ContactFormWithPriority(auto_id=False) >>> print(f.as_div()) <div>Subject:<input type="text" name="subject" maxlength="100" required></div> <div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div> <div>Sender:<input type="email" name="sender" required></div> <div>Cc myself:<input type="checkbox" name="cc_myself"></div> <div>Priority:<input type="text" name="priority" required></div>
It’s possible to subclass multiple forms, treating forms as mixins. In this
example, BeatleForm
subclasses both PersonForm
and InstrumentForm
(in that order), and its field list includes the fields from the parent
classes:
>>> from django import forms >>> class PersonForm(forms.Form): ... first_name = forms.CharField() ... last_name = forms.CharField() ... >>> class InstrumentForm(forms.Form): ... instrument = forms.CharField() ... >>> class BeatleForm(InstrumentForm, PersonForm): ... haircut_type = forms.CharField() ... >>> b = BeatleForm(auto_id=False) >>> print(b.as_div()) <div>First name:<input type="text" name="first_name" required></div> <div>Last name:<input type="text" name="last_name" required></div> <div>Instrument:<input type="text" name="instrument" required></div> <div>Haircut type:<input type="text" name="haircut_type" required></div>
It’s possible to declaratively remove a Field
inherited from a parent class
by setting the name of the field to None
on the subclass. For example:
>>> from django import forms >>> class ParentForm(forms.Form): ... name = forms.CharField() ... age = forms.IntegerField() ... >>> class ChildForm(ParentForm): ... name = None ... >>> list(ChildForm().fields) ['age']
Prefixes for forms¶
- Form.prefix¶
You can put several Django forms inside one <form>
tag. To give each
Form
its own namespace, use the prefix
keyword argument:
>>> mother = PersonForm(prefix="mother") >>> father = PersonForm(prefix="father") >>> print(mother.as_div()) <div><label for="id_mother-first_name">First name:</label><input type="text" name="mother-first_name" required id="id_mother-first_name"></div> <div><label for="id_mother-last_name">Last name:</label><input type="text" name="mother-last_name" required id="id_mother-last_name"></div> >>> print(father.as_div()) <div><label for="id_father-first_name">First name:</label><input type="text" name="father-first_name" required id="id_father-first_name"></div> <div><label for="id_father-last_name">Last name:</label><input type="text" name="father-last_name" required id="id_father-last_name"></div>
The prefix can also be specified on the form class:
>>> class PersonForm(forms.Form): ... ... ... prefix = "person" ...
This is my view:
def main_page(request):
if request.method == 'POST':
form = RegistrationForm(request.POST)
if form.is_valid():
user = User.objects.create_user(
username=form.clean_data['username'],
password=form.clean_data['password1'],
email=form.clean_data['email']
)
return HttpResponseRedirect('/')
else:
form = RegistrationForm()
variables = {
'form': form
}
return render(request, 'main_page.html', variables)
and this is my main_page.html:
{% if form.errors %}
<p>NOT VALID</p>
{% for errors in form.errors %}
{{ errors }}
{% endfor %}
{% endif %}
<form method="post" action="/">{% csrf_token %}
<p><label for="id_username">Username:</label>{{ form.username }}</p>
<p><label for="id_email">Email Address:</label>{{ form.email }}</p>
<p><label for="id_password">Password:</label>{{ form.password1 }}</p>
<p><label for="id_retypePassword">Retype Password:</label>{{ form.password2 }}</p>
<input type="hidden" name="next" />
<input type="submit" value="Register" />
</form>
When I go to the url which uses the main_page view, it just displays the form. When I submit the form with errors (with blank fields and without a proper email address) it just redirects me to the same page and doesn’t display any errors. It doesn’t even say «NOT VALID».
When I change
{% if form.errors %}
to
{% if not form.is_valid %}
it always says «NOT VALID» (even if it is the first time going to the url and even if I didn’t submit anything yet).
This is my RegistrationForm:
from django import forms
import re
from django.contrib.auth.models import User
from django.core.exceptions import ObjectDoesNotExist
class RegistrationForm(forms.Form):
username = forms.CharField(label='Username', max_length=30)
email = forms.EmailField(label='Email')
password1 = forms.CharField(label='Password', widget=forms.PasswordInput())
password2 = forms.CharField(label='Password (Again)', widget=forms.PasswordInput())
def clean_password2(self):
if 'password1' in self.cleaned_data:
password1 = self.cleaned_data['password1']
password2 = self.cleaned_data['password2']
if password1 == password2:
return password2
raise forms.ValidationError('Passwords do not match.')
def clean_username(self):
username = self.cleaned_data['username']
if not re.search(r'^w+$', username): #checks if all the characters in username are in the regex. If they aren't, it returns None
raise forms.ValidationError('Username can only contain alphanumeric characters and the underscore.')
try:
User.objects.get(username=username) #this raises an ObjectDoesNotExist exception if it doesn't find a user with that username
except ObjectDoesNotExist:
return username #if username doesn't exist, this is good. We can create the username
raise forms.ValidationError('Username is already taken.')