mirror of
https://github.com/django/django.git
synced 2024-12-27 03:25:58 +00:00
121fd109de
cleaned_data is no longer deleted when form validation fails but only contains the data that did validate. Thanks to the various contributors to this patch (see ticket).
799 lines
37 KiB
Plaintext
799 lines
37 KiB
Plaintext
=============
|
|
The Forms API
|
|
=============
|
|
|
|
.. module:: django.forms.forms
|
|
|
|
.. currentmodule:: django.forms
|
|
|
|
.. admonition:: About this document
|
|
|
|
This document covers the gritty details of Django's forms API. You should
|
|
read the :doc:`introduction to working with forms </topics/forms/index>`
|
|
first.
|
|
|
|
.. _ref-forms-api-bound-unbound:
|
|
|
|
Bound and unbound forms
|
|
-----------------------
|
|
|
|
A :class:`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 :class:`Form` instance, simply instantiate the class::
|
|
|
|
>>> f = ContactForm()
|
|
|
|
To bind data to a form, pass the data as a dictionary as the first parameter to
|
|
your :class:`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 :class:`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 :class:`Field`, as we'll see
|
|
in a moment.
|
|
|
|
.. attribute:: Form.is_bound
|
|
|
|
If you need to distinguish between bound and unbound form instances at runtime,
|
|
check the value of the form's :attr:`~Form.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 :class:`Form` instance and want to change the data somehow,
|
|
or if you want to bind an unbound :class:`Form` instance to some data, create
|
|
another :class:`Form` instance. There is no way to change data in a
|
|
:class:`Form` instance. Once a :class:`Form` instance has been created, you
|
|
should consider its data immutable, whether it has data or not.
|
|
|
|
Using forms to validate data
|
|
----------------------------
|
|
|
|
.. method:: Form.is_valid()
|
|
|
|
The primary task of a :class:`Form` object is to validate data. With a bound
|
|
:class:`Form` instance, call the :meth:`~Form.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
|
|
|
|
.. attribute:: Form.errors
|
|
|
|
Access the :attr:`~Form.errors` attribute to get a dictionary of error
|
|
messages::
|
|
|
|
>>> f.errors
|
|
{'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']}
|
|
|
|
In this dictionary, the keys are the field names, and the values are lists of
|
|
Unicode strings representing the error messages. The error messages are stored
|
|
in lists because a field can have multiple error messages.
|
|
|
|
You can access :attr:`~Form.errors` without having to call
|
|
:meth:`~Form.is_valid` first. The form's data will be validated the first time
|
|
either you call :meth:`~Form.is_valid` or access :attr:`~Form.errors`.
|
|
|
|
The validation routines will only get called once, regardless of how many times
|
|
you access :attr:`~Form.errors` or call :meth:`~Form.is_valid`. This means that
|
|
if validation has side effects, those side effects will only be triggered once.
|
|
|
|
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
|
|
{}
|
|
|
|
Dynamic initial values
|
|
----------------------
|
|
|
|
.. attribute:: Form.initial
|
|
|
|
Use :attr:`~Form.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 :attr:`~Form.initial` argument to a :class:`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.
|
|
|
|
Note that if a :class:`~django.forms.fields.Field` defines
|
|
:attr:`~Form.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::
|
|
|
|
>>> 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" /></td></tr>
|
|
<tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
|
|
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
|
|
|
|
Accessing "clean" data
|
|
----------------------
|
|
|
|
.. attribute:: Form.cleaned_data
|
|
|
|
Each field in a :class:`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, :class:`~django.forms.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 :class:`~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': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
|
|
|
|
Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
|
|
always cleans the input into a Unicode 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': u'Hi there'}
|
|
|
|
.. versionchanged:: 1.5
|
|
|
|
Until Django 1.5, the ``cleaned_data`` attribute wasn't defined at all when
|
|
the ``Form`` didn't validate.
|
|
|
|
``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': u'Hi there', 'sender': u'foo@example.com', 'subject': u'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::
|
|
|
|
>>> class OptionalPersonForm(Form):
|
|
... first_name = CharField()
|
|
... last_name = CharField()
|
|
... nick_name = CharField(required=False)
|
|
>>> data = {'first_name': u'John', 'last_name': u'Lennon'}
|
|
>>> f = OptionalPersonForm(data)
|
|
>>> f.is_valid()
|
|
True
|
|
>>> f.cleaned_data
|
|
{'nick_name': u'', 'first_name': u'John', 'last_name': u'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 :doc:`/ref/forms/validation`.
|
|
|
|
Outputting forms as HTML
|
|
------------------------
|
|
|
|
The second task of a ``Form`` object is to render itself as HTML. To do so,
|
|
simply ``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" /></td></tr>
|
|
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
|
|
<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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="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" /></td></tr>
|
|
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr>
|
|
<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></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="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`` and
|
|
``EmailField`` are represented by an ``<input type="text">``.
|
|
``BooleanField`` 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 the ``ContactForm`` 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 its ``id``. Its ``id``, in turn, is
|
|
generated by prepending ``'id_'`` to the field name. The ``id``
|
|
attributes and ``<label>`` tags are included in the output by default, to
|
|
follow best practices, but you can change that behavior.
|
|
|
|
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 Unicode object.
|
|
|
|
``as_p()``
|
|
~~~~~~~~~~
|
|
|
|
.. method:: 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()
|
|
u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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" /></p>
|
|
<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>
|
|
<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>
|
|
<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
|
|
|
|
``as_ul()``
|
|
~~~~~~~~~~~
|
|
|
|
.. method:: 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()
|
|
u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></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" /></li>
|
|
<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>
|
|
<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>
|
|
<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
|
|
|
|
``as_table()``
|
|
~~~~~~~~~~~~~~
|
|
|
|
.. method:: Form.as_table
|
|
|
|
Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is
|
|
exactly the same as ``print``. In fact, when you ``print`` a form object,
|
|
it calls its ``as_table()`` method behind the scenes::
|
|
|
|
>>> f = ContactForm()
|
|
>>> f.as_table()
|
|
u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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.as_table())
|
|
<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
|
|
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
|
|
<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></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
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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 :class:`Form` class has a couple of hooks you can use to add ``class``
|
|
attributes to required rows or to rows with errors: simply set the
|
|
:attr:`Form.error_css_class` and/or :attr:`Form.required_css_class`
|
|
attributes::
|
|
|
|
class ContactForm(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 for="id_subject">Subject:</label> ...
|
|
<tr class="required"><th><label for="id_message">Message:</label> ...
|
|
<tr class="required error"><th><label for="id_sender">Sender:</label> ...
|
|
<tr><th><label for="id_cc_myself">Cc myself:<label> ...
|
|
|
|
.. _ref-forms-api-configuring-label:
|
|
|
|
Configuring HTML ``<label>`` tags
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
By default, the form rendering methods include HTML ``id`` attributes on the
|
|
form elements and corresponding ``<label>`` tags around the labels. 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 label
|
|
and ``id`` 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_table())
|
|
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr>
|
|
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
|
|
<tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr>
|
|
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
|
|
>>> print(f.as_ul())
|
|
<li>Subject: <input type="text" name="subject" maxlength="100" /></li>
|
|
<li>Message: <input type="text" name="message" /></li>
|
|
<li>Sender: <input type="text" name="sender" /></li>
|
|
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
|
|
>>> print(f.as_p())
|
|
<p>Subject: <input type="text" name="subject" maxlength="100" /></p>
|
|
<p>Message: <input type="text" name="message" /></p>
|
|
<p>Sender: <input type="text" name="sender" /></p>
|
|
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
|
|
|
|
If ``auto_id`` is set to ``True``, then the form output *will* include
|
|
``<label>`` tags and will simply use the field name as its ``id`` for each form
|
|
field::
|
|
|
|
>>> f = ContactForm(auto_id=True)
|
|
>>> print(f.as_table())
|
|
<tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr>
|
|
<tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr>
|
|
<tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr>
|
|
<tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr>
|
|
>>> print(f.as_ul())
|
|
<li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li>
|
|
<li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li>
|
|
<li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li>
|
|
<li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li>
|
|
>>> print(f.as_p())
|
|
<p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p>
|
|
<p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p>
|
|
<p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p>
|
|
<p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p>
|
|
|
|
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_table())
|
|
<tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr>
|
|
<tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr>
|
|
<tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr>
|
|
<tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr>
|
|
>>> print(f.as_ul())
|
|
<li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
|
|
<li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li>
|
|
<li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li>
|
|
<li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
|
|
>>> print(f.as_p())
|
|
<p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p>
|
|
<p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p>
|
|
<p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p>
|
|
<p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p>
|
|
|
|
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'``.
|
|
|
|
Normally, a colon (``:``) will be appended after any label name when a form is
|
|
rendered. It's possible to change the colon to another character, or omit it
|
|
entirely, using the ``label_suffix`` parameter::
|
|
|
|
>>> f = ContactForm(auto_id='id_for_%s', label_suffix='')
|
|
>>> print(f.as_ul())
|
|
<li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
|
|
<li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li>
|
|
<li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li>
|
|
<li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
|
|
>>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->')
|
|
>>> print(f.as_ul())
|
|
<li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
|
|
<li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li>
|
|
<li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li>
|
|
<li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
|
|
|
|
Note that the label suffix is added only if the last character of the
|
|
label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``)
|
|
|
|
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, just change the order in which those fields are listed in the class.
|
|
|
|
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_table())
|
|
<tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr>
|
|
<tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr>
|
|
<tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid email address" /></td></tr>
|
|
<tr><th>Cc myself:</th><td><input checked="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" /></li>
|
|
<li>Message: <input type="text" name="message" value="Hi there" /></li>
|
|
<li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid email address" /></li>
|
|
<li>Cc myself: <input checked="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" /></p>
|
|
<p>Message: <input type="text" name="message" value="Hi there" /></p>
|
|
<p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p>
|
|
<p>Sender: <input type="text" name="sender" value="invalid email address" /></p>
|
|
<p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
|
|
|
|
Customizing the error list format
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
By default, forms use ``django.forms.util.ErrorList`` to format validation
|
|
errors. If you'd like to use an alternate class for displaying errors, you can
|
|
pass that in at construction time::
|
|
|
|
>>> from django.forms.util import ErrorList
|
|
>>> class DivErrorList(ErrorList):
|
|
... def __unicode__(self):
|
|
... return self.as_divs()
|
|
... def as_divs(self):
|
|
... if not self: return u''
|
|
... return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
|
|
>>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
|
|
>>> f.as_p()
|
|
<div class="errorlist"><div class="error">This field is required.</div></div>
|
|
<p>Subject: <input type="text" name="subject" maxlength="100" /></p>
|
|
<p>Message: <input type="text" name="message" value="Hi there" /></p>
|
|
<div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div>
|
|
<p>Sender: <input type="text" name="sender" value="invalid email address" /></p>
|
|
<p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
|
|
|
|
More granular output
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
|
|
lazy developers -- 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
|
|
:class:`Form` instance.
|
|
|
|
The :meth:`__unicode__` and :meth:`__str__` methods 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" />
|
|
|
|
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" />
|
|
<input type="text" name="message" id="id_message" />
|
|
<input type="text" name="sender" id="id_sender" />
|
|
<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" />
|
|
>>> f = ContactForm(auto_id='id_%s')
|
|
>>> print(f['message'])
|
|
<input type="text" name="message" id="id_message" />
|
|
|
|
For a field's list of errors, access the field's ``errors`` attribute.
|
|
|
|
.. attribute:: 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" />
|
|
>>> f['message'].errors
|
|
[u'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)
|
|
''
|
|
|
|
.. method:: BoundField.css_classes()
|
|
|
|
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)
|
|
>>> 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)
|
|
>>> f['message'].css_classes('foo bar')
|
|
'foo bar required'
|
|
|
|
.. method:: BoundField.value()
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
Use this method to render the raw value of this field as it would be rendered
|
|
by a ``Widget``::
|
|
|
|
>>> initial = {'subject': 'welcome'}
|
|
>>> unbound_form = ContactForm(initial=initial)
|
|
>>> bound_form = ContactForm(data, initial=initial)
|
|
>>> print(unbound_form['subject'].value())
|
|
welcome
|
|
>>> print(bound_form['subject'].value())
|
|
hi
|
|
|
|
.. _binding-uploaded-files:
|
|
|
|
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', <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 -- just omit both
|
|
form data *and* file data::
|
|
|
|
# Unbound form with a image field
|
|
>>> f = ContactFormWithMugshot()
|
|
|
|
Testing for multipart forms
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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_ul())
|
|
<li>Subject: <input type="text" name="subject" maxlength="100" /></li>
|
|
<li>Message: <input type="text" name="message" /></li>
|
|
<li>Sender: <input type="text" name="sender" /></li>
|
|
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
|
|
<li>Priority: <input type="text" name="priority" /></li>
|
|
|
|
It's possible to subclass multiple forms, treating forms as "mix-ins." In this
|
|
example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm``
|
|
(in that order), and its field list includes the fields from the parent
|
|
classes::
|
|
|
|
>>> class PersonForm(Form):
|
|
... first_name = CharField()
|
|
... last_name = CharField()
|
|
>>> class InstrumentForm(Form):
|
|
... instrument = CharField()
|
|
>>> class BeatleForm(PersonForm, InstrumentForm):
|
|
... haircut_type = CharField()
|
|
>>> b = BeatleForm(auto_id=False)
|
|
>>> print(b.as_ul())
|
|
<li>First name: <input type="text" name="first_name" /></li>
|
|
<li>Last name: <input type="text" name="last_name" /></li>
|
|
<li>Instrument: <input type="text" name="instrument" /></li>
|
|
<li>Haircut type: <input type="text" name="haircut_type" /></li>
|
|
|
|
.. _form-prefix:
|
|
|
|
Prefixes for forms
|
|
------------------
|
|
|
|
.. attribute:: 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_ul())
|
|
<li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
|
|
<li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
|
|
>>> print(father.as_ul())
|
|
<li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
|
|
<li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>
|