1421 lines
61 KiB
Plaintext
1421 lines
61 KiB
Plaintext
====================
|
|
The newforms library
|
|
====================
|
|
|
|
``django.newforms`` is Django's fantastic new form-handling library. It's a
|
|
replacement for ``django.forms``, the old form/manipulator/validation
|
|
framework. This document explains how to use this new library.
|
|
|
|
Migration plan
|
|
==============
|
|
|
|
``django.newforms`` is new in Django's 0.96 release, but, as it won't be new
|
|
forever, we plan to rename it to ``django.forms`` in the future. The current
|
|
``django.forms`` package will be available as ``django.oldforms`` until Django
|
|
1.0, when we plan to remove it for good.
|
|
|
|
That has direct repercussions on the forward compatibility of your code. Please
|
|
read the following migration plan and code accordingly:
|
|
|
|
* The old forms framework (the current ``django.forms``) has been copied to
|
|
``django.oldforms``. Thus, you can start upgrading your code *now*,
|
|
rather than waiting for the future backwards-incompatible change, by
|
|
changing your import statements like this::
|
|
|
|
from django import forms # old
|
|
from django import oldforms as forms # new
|
|
|
|
* In the next Django release (0.97), we will move the current
|
|
``django.newforms`` to ``django.forms``. This will be a
|
|
backwards-incompatible change, and anybody who is still using the old
|
|
version of ``django.forms`` at that time will need to change their import
|
|
statements, as described in the previous bullet.
|
|
|
|
* We will remove ``django.oldforms`` in the release *after* the next Django
|
|
release -- either 0.98 or 1.0, whichever comes first.
|
|
|
|
With this in mind, we recommend you use the following import statement when
|
|
using ``django.newforms``::
|
|
|
|
from django import newforms as forms
|
|
|
|
This way, your code can refer to the ``forms`` module, and when
|
|
``django.newforms`` is renamed to ``django.forms``, you'll only have to change
|
|
your ``import`` statements.
|
|
|
|
If you prefer "``import *``" syntax, you can do the following::
|
|
|
|
from django.newforms import *
|
|
|
|
This will import all fields, widgets, form classes and other various utilities
|
|
into your local namespace. Some people find this convenient; others find it
|
|
too messy. The choice is yours.
|
|
|
|
Overview
|
|
========
|
|
|
|
As with the ``django.forms`` ("manipulators") system before it,
|
|
``django.newforms`` is intended to handle HTML form display, data processing
|
|
(validation) and redisplay. It's what you use if you want to perform
|
|
server-side validation for an HTML form.
|
|
|
|
For example, if your Web site has a contact form that visitors can use to
|
|
send you e-mail, you'd use this library to implement the display of the HTML
|
|
form fields, along with the form validation. Any time you need to use an HTML
|
|
``<form>``, you can use this library.
|
|
|
|
The library deals with these concepts:
|
|
|
|
* **Widget** -- A class that corresponds to an HTML form widget, e.g.
|
|
``<input type="text">`` or ``<textarea>``. This handles rendering of the
|
|
widget as HTML.
|
|
|
|
* **Field** -- A class that is responsible for doing validation, e.g.
|
|
an ``EmailField`` that makes sure its data is a valid e-mail address.
|
|
|
|
* **Form** -- A collection of fields that knows how to validate itself and
|
|
display itself as HTML.
|
|
|
|
The library is decoupled from the other Django components, such as the database
|
|
layer, views and templates. It relies only on Django settings, a couple of
|
|
``django.utils`` helper functions and Django's internationalization hooks (but
|
|
you're not required to be using internationalization features to use this
|
|
library).
|
|
|
|
Form objects
|
|
============
|
|
|
|
The primary way of using the ``newforms`` library is to create a form object.
|
|
Do this by subclassing ``django.newforms.Form`` and specifying the form's
|
|
fields, in a declarative style that you'll be familiar with if you've used
|
|
Django database models. In this section, we'll iteratively develop a form
|
|
object that you might use to implement "contact me" functionality on your
|
|
personal Web site.
|
|
|
|
Start with this basic ``Form`` subclass, which we'll call ``ContactForm``::
|
|
|
|
from django import newforms as forms
|
|
|
|
class ContactForm(forms.Form):
|
|
subject = forms.CharField(max_length=100)
|
|
message = forms.CharField()
|
|
sender = forms.EmailField()
|
|
cc_myself = forms.BooleanField()
|
|
|
|
A form is composed of ``Field`` objects. In this case, our form has four
|
|
fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain
|
|
the different types of fields -- e.g., ``CharField`` and ``EmailField`` --
|
|
shortly.
|
|
|
|
Creating ``Form`` instances
|
|
---------------------------
|
|
|
|
A ``Form`` instance is either **bound** or **unbound** to a set of data.
|
|
|
|
* 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.
|
|
|
|
To create an unbound ``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 ``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.
|
|
|
|
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
|
|
----------------------------
|
|
|
|
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
|
|
e-mail address::
|
|
|
|
>>> data = {'subject': '',
|
|
... 'message': 'Hi there',
|
|
... 'sender': 'invalid e-mail address',
|
|
... 'cc_myself': True}
|
|
>>> f = ContactForm(data)
|
|
>>> f.is_valid()
|
|
False
|
|
|
|
Access the ``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 ``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.
|
|
|
|
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
|
|
{}
|
|
|
|
Accessing "clean" 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 the ``clean_data`` attribute of the ``Form``
|
|
object::
|
|
|
|
>>> data = {'subject': 'hello',
|
|
... 'message': 'Hi there',
|
|
... 'sender': 'foo@example.com',
|
|
... 'cc_myself': True}
|
|
>>> f = ContactForm(data)
|
|
>>> f.is_valid()
|
|
True
|
|
>>> f.clean_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, your ``Form`` instance will not have a
|
|
``clean_data`` attribute::
|
|
|
|
>>> data = {'subject': '',
|
|
... 'message': 'Hi there',
|
|
... 'sender': 'invalid e-mail address',
|
|
... 'cc_myself': True}
|
|
>>> f = ContactForm(data)
|
|
>>> f.is_valid()
|
|
False
|
|
>>> f.clean_data
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: 'ContactForm' object has no attribute 'clean_data'
|
|
|
|
``clean_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 ``clean_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.clean_data # Doesn't contain extra_field_1, etc.
|
|
{'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
|
|
|
|
``clean_data`` will include a key and value for *all* fields defined in the
|
|
``Form``, even if the data didn't include a value for fields that are not
|
|
required. In this example, the data dictionary doesn't include a value for the
|
|
``nick_name`` field, but ``clean_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.clean_data
|
|
{'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
|
|
|
|
In this above example, the ``clean_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.
|
|
|
|
Behavior of unbound forms
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
It's meaningless to request "clean" data in a form with no data, but, for the
|
|
record, here's what happens with unbound forms::
|
|
|
|
>>> f = ContactForm()
|
|
>>> f.clean_data
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: 'ContactForm' object has no attribute 'clean_data'
|
|
|
|
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()``
|
|
~~~~~~~~~~
|
|
|
|
``Form.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()``
|
|
~~~~~~~~~~~
|
|
|
|
``Form.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()``
|
|
~~~~~~~~~~~~~~
|
|
|
|
Finally, ``Form.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>
|
|
|
|
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'``.
|
|
|
|
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 e-mail 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 e-mail 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 e-mail 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 e-mail 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.
|
|
|
|
To display the HTML for a single field in your form, use dictionary lookup
|
|
syntax using the field's name as the key, and print the resulting object::
|
|
|
|
>>> f = ContactForm()
|
|
>>> print f['subject']
|
|
<input id="id_subject" type="text" name="subject" maxlength="100" />
|
|
>>> print f['message']
|
|
<input type="text" name="message" id="id_message" />
|
|
>>> print f['sender']
|
|
<input type="text" name="sender" id="id_sender" />
|
|
>>> print f['cc_myself']
|
|
<input type="checkbox" name="cc_myself" id="id_cc_myself" />
|
|
|
|
Call ``str()`` or ``unicode()`` on the field to get its rendered HTML as a
|
|
string or Unicode object, respectively::
|
|
|
|
>>> str(f['subject'])
|
|
'<input id="id_subject" type="text" name="subject" maxlength="100" />'
|
|
>>> unicode(f['subject'])
|
|
u'<input id="id_subject" type="text" name="subject" maxlength="100" />'
|
|
|
|
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. This
|
|
is 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)
|
|
''
|
|
|
|
Subclassing forms
|
|
-----------------
|
|
|
|
If you subclass a custom ``Form`` class, the resulting ``Form`` class 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>
|
|
|
|
Fields
|
|
======
|
|
|
|
When you create a ``Form`` class, the most important part is defining the
|
|
fields of the form. Each field has custom validation logic, along with a few
|
|
other hooks.
|
|
|
|
Although the primary way you'll use ``Field`` classes is in ``Form`` classes,
|
|
you can also instantiate them and use them directly to get a better idea of
|
|
how they work. Each ``Field`` instance has a ``clean()`` method, which takes
|
|
a single argument and either raises a ``django.newforms.ValidationError``
|
|
exception or returns the clean value::
|
|
|
|
>>> f = forms.EmailField()
|
|
>>> f.clean('foo@example.com')
|
|
u'foo@example.com'
|
|
>>> f.clean(u'foo@example.com')
|
|
u'foo@example.com'
|
|
>>> f.clean('invalid e-mail address')
|
|
Traceback (most recent call last):
|
|
...
|
|
ValidationError: [u'Enter a valid e-mail address.']
|
|
|
|
If you've used Django's old forms/validation framework, take care in noticing
|
|
this ``ValidationError`` is different than the previous ``ValidationError``.
|
|
This one lives at ``django.newforms.ValidationError`` rather than
|
|
``django.core.validators.ValidationError``.
|
|
|
|
Core field arguments
|
|
--------------------
|
|
|
|
Each ``Field`` class constructor takes at least these arguments. Some
|
|
``Field`` classes take additional, field-specific arguments, but the following
|
|
should *always* be accepted:
|
|
|
|
``required``
|
|
~~~~~~~~~~~~
|
|
|
|
By default, each ``Field`` class assumes the value is required, so if you pass
|
|
an empty value -- either ``None`` or the empty string (``""``) -- then
|
|
``clean()`` will raise a ``ValidationError`` exception::
|
|
|
|
>>> f = forms.CharField()
|
|
>>> f.clean('foo')
|
|
u'foo'
|
|
>>> f.clean('')
|
|
Traceback (most recent call last):
|
|
...
|
|
ValidationError: [u'This field is required.']
|
|
>>> f.clean(None)
|
|
Traceback (most recent call last):
|
|
...
|
|
ValidationError: [u'This field is required.']
|
|
>>> f.clean(' ')
|
|
u' '
|
|
>>> f.clean(0)
|
|
u'0'
|
|
>>> f.clean(True)
|
|
u'True'
|
|
>>> f.clean(False)
|
|
u'False'
|
|
|
|
To specify that a field is *not* required, pass ``required=False`` to the
|
|
``Field`` constructor::
|
|
|
|
>>> f = forms.CharField(required=False)
|
|
>>> f.clean('foo')
|
|
u'foo'
|
|
>>> f.clean('')
|
|
u''
|
|
>>> f.clean(None)
|
|
u''
|
|
>>> f.clean(0)
|
|
u'0'
|
|
>>> f.clean(True)
|
|
u'True'
|
|
>>> f.clean(False)
|
|
u'False'
|
|
|
|
If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value,
|
|
then ``clean()`` will return a *normalized* empty value rather than raising
|
|
``ValidationError``. For ``CharField``, this will be a Unicode empty string.
|
|
For other ``Field`` classes, it might be ``None``. (This varies from field to
|
|
field.)
|
|
|
|
``label``
|
|
~~~~~~~~~
|
|
|
|
The ``label`` argument lets you specify the "human-friendly" label for this
|
|
field. This is used when the ``Field`` is displayed in a ``Form``.
|
|
|
|
As explained in "Outputting forms as HTML" above, the default label for a
|
|
``Field`` is generated from the field name by converting all underscores to
|
|
spaces and upper-casing the first letter. Specify ``label`` if that default
|
|
behavior doesn't result in an adequate label.
|
|
|
|
Here's a full example ``Form`` that implements ``label`` for two of its fields.
|
|
We've specified ``auto_id=False`` to simplify the output::
|
|
|
|
>>> class CommentForm(forms.Form):
|
|
... name = forms.CharField(label='Your name')
|
|
... url = forms.URLField(label='Your Web site', required=False)
|
|
... comment = forms.CharField()
|
|
>>> f = CommentForm(auto_id=False)
|
|
>>> print f
|
|
<tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
|
|
<tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr>
|
|
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
|
|
|
|
``initial``
|
|
~~~~~~~~~~~
|
|
|
|
The ``initial`` argument lets you specify the initial value to use when
|
|
rendering this ``Field`` in an unbound ``Form``.
|
|
|
|
The use-case for this is when you want to display an "empty" form in which a
|
|
field is initialized to a particular value. For example::
|
|
|
|
>>> class CommentForm(forms.Form):
|
|
... name = forms.CharField(initial='Your name')
|
|
... url = forms.URLField(initial='http://')
|
|
... comment = forms.CharField()
|
|
>>> f = CommentForm(auto_id=False)
|
|
>>> print f
|
|
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
|
|
<tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr>
|
|
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
|
|
|
|
You may be thinking, why not just pass a dictionary of the initial values as
|
|
data when displaying the form? Well, if you do that, you'll trigger validation,
|
|
and the HTML output will include any validation errors::
|
|
|
|
>>> class CommentForm(forms.Form):
|
|
... name = forms.CharField()
|
|
... url = forms.URLField()
|
|
... comment = forms.CharField()
|
|
>>> default_data = {'name': 'Your name', 'url': 'http://'}
|
|
>>> f = CommentForm(default_data, auto_id=False)
|
|
>>> print f
|
|
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
|
|
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr>
|
|
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr>
|
|
|
|
This is why ``initial`` values are only displayed for unbound forms. For bound
|
|
forms, the HTML output will use the bound data.
|
|
|
|
Also note that ``initial`` values are *not* used as "fallback" data in
|
|
validation if a particular field's value is not given. ``initial`` values are
|
|
*only* intended for initial form display::
|
|
|
|
>>> class CommentForm(forms.Form):
|
|
... name = forms.CharField(initial='Your name')
|
|
... url = forms.URLField(initial='http://')
|
|
... comment = forms.CharField()
|
|
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
|
|
>>> f = CommentForm(data)
|
|
>>> f.is_valid()
|
|
False
|
|
# The form does *not* fall back to using the initial values.
|
|
>>> f.errors
|
|
{'url': [u'This field is required.'], 'name': [u'This field is required.']}
|
|
|
|
``widget``
|
|
~~~~~~~~~~
|
|
|
|
The ``widget`` argument lets you specify a ``Widget`` class to use when
|
|
rendering this ``Field``. See "Widgets" below for more information.
|
|
|
|
``help_text``
|
|
~~~~~~~~~~~~~
|
|
|
|
The ``help_text`` argument lets you specify descriptive text for this
|
|
``Field``. If you provide ``help_text``, it will be displayed next to the
|
|
``Field`` when the ``Field`` is rendered by one of the convenience ``Form``
|
|
methods (e.g., ``as_ul()``).
|
|
|
|
Here's a full example ``Form`` that implements ``help_text`` for two of its
|
|
fields. We've specified ``auto_id=False`` to simplify the output::
|
|
|
|
>>> class HelpTextContactForm(forms.Form):
|
|
... subject = forms.CharField(max_length=100, help_text='100 characters max.')
|
|
... message = forms.CharField()
|
|
... sender = forms.EmailField(help_text='A valid e-mail address, please.')
|
|
... cc_myself = forms.BooleanField()
|
|
>>> f = HelpTextContactForm(auto_id=False)
|
|
>>> print f.as_table()
|
|
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
|
|
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
|
|
<tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</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" /> 100 characters max.</li>
|
|
<li>Message: <input type="text" name="message" /></li>
|
|
<li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
|
|
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
|
|
>>> print f.as_p()
|
|
<p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
|
|
<p>Message: <input type="text" name="message" /></p>
|
|
<p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
|
|
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
|
|
|
|
Dynamic initial values
|
|
----------------------
|
|
|
|
The ``initial`` argument to ``Field`` (explained above) lets you hard-code the
|
|
initial value for a ``Field`` -- but what if you want to declare the initial
|
|
value 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::
|
|
|
|
>>> class CommentForm(forms.Form):
|
|
... name = forms.CharField()
|
|
... url = forms.URLField()
|
|
... comment = forms.CharField()
|
|
>>> f = CommentForm(initial={'name': 'your username'}, auto_id=False)
|
|
>>> print f
|
|
<tr><th>Name:</th><td><input type="text" name="name" value="your username" /></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>
|
|
>>> f = CommentForm(initial={'name': 'another username'}, auto_id=False)
|
|
>>> print f
|
|
<tr><th>Name:</th><td><input type="text" name="name" value="another username" /></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>
|
|
|
|
Just like the ``initial`` parameter to ``Field``, these values are only
|
|
displayed for unbound forms, and they're not used as fallback values if a
|
|
particular value isn't provided.
|
|
|
|
Finally, note that 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::
|
|
|
|
>>> 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>
|
|
|
|
Built-in ``Field`` classes
|
|
--------------------------
|
|
|
|
Naturally, the ``newforms`` library comes with a set of ``Field`` classes that
|
|
represent common validation needs. This section documents each built-in field.
|
|
|
|
For each field, we describe the default widget used if you don't specify
|
|
``widget``. We also specify the value returned when you provide an empty value
|
|
(see the section on ``required`` above to understand what that means).
|
|
|
|
``BooleanField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``CheckboxInput``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python ``True`` or ``False`` value.
|
|
* Validates nothing (i.e., it never raises a ``ValidationError``).
|
|
|
|
``CharField``
|
|
~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``''`` (an empty string)
|
|
* Normalizes to: A Unicode object.
|
|
* Validates nothing, unless ``max_length`` or ``min_length`` is provided.
|
|
|
|
Has two optional arguments for validation, ``max_length`` and ``min_length``.
|
|
If provided, these arguments ensure that the string is at most or at least the
|
|
given length.
|
|
|
|
``ChoiceField``
|
|
~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``Select``
|
|
* Empty value: ``''`` (an empty string)
|
|
* Normalizes to: A Unicode object.
|
|
* Validates that the given value exists in the list of choices.
|
|
|
|
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
|
|
tuple) of 2-tuples to use as choices for this field.
|
|
|
|
``DateField``
|
|
~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python ``datetime.date`` object.
|
|
* Validates that the given value is either a ``datetime.date``,
|
|
``datetime.datetime`` or string formatted in a particular date format.
|
|
|
|
Takes one optional argument, ``input_formats``, which is a list of formats used
|
|
to attempt to convert a string to a valid ``datetime.date`` object.
|
|
|
|
If no ``input_formats`` argument is provided, the default input formats are::
|
|
|
|
'%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
|
|
'%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006'
|
|
'%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006'
|
|
'%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006'
|
|
'%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006'
|
|
|
|
``DateTimeField``
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python ``datetime.datetime`` object.
|
|
* Validates that the given value is either a ``datetime.datetime``,
|
|
``datetime.date`` or string formatted in a particular datetime format.
|
|
|
|
Takes one optional argument, ``input_formats``, which is a list of formats used
|
|
to attempt to convert a string to a valid ``datetime.datetime`` object.
|
|
|
|
If no ``input_formats`` argument is provided, the default input formats are::
|
|
|
|
'%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59'
|
|
'%Y-%m-%d %H:%M', # '2006-10-25 14:30'
|
|
'%Y-%m-%d', # '2006-10-25'
|
|
'%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59'
|
|
'%m/%d/%Y %H:%M', # '10/25/2006 14:30'
|
|
'%m/%d/%Y', # '10/25/2006'
|
|
'%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59'
|
|
'%m/%d/%y %H:%M', # '10/25/06 14:30'
|
|
'%m/%d/%y', # '10/25/06'
|
|
|
|
``EmailField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``''`` (an empty string)
|
|
* Normalizes to: A Unicode object.
|
|
* Validates that the given value is a valid e-mail address, using a
|
|
moderately complex regular expression.
|
|
|
|
Has two optional arguments for validation, ``max_length`` and ``min_length``.
|
|
If provided, these arguments ensure that the string is at most or at least the
|
|
given length.
|
|
|
|
``IntegerField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python integer or long integer.
|
|
* Validates that the given value is an integer. Leading and trailing
|
|
whitespace is allowed, as in Python's ``int()`` function.
|
|
|
|
``MultipleChoiceField``
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``SelectMultiple``
|
|
* Empty value: ``[]`` (an empty list)
|
|
* Normalizes to: A list of Unicode objects.
|
|
* Validates that every value in the given list of values exists in the list
|
|
of choices.
|
|
|
|
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
|
|
tuple) of 2-tuples to use as choices for this field.
|
|
|
|
``NullBooleanField``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``NullBooleanSelect``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python ``True``, ``False`` or ``None`` value.
|
|
* Validates nothing (i.e., it never raises a ``ValidationError``).
|
|
|
|
``RegexField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``''`` (an empty string)
|
|
* Normalizes to: A Unicode object.
|
|
* Validates that the given value matches against a certain regular
|
|
expression.
|
|
|
|
Takes one required argument, ``regex``, which is a regular expression specified
|
|
either as a string or a compiled regular expression object.
|
|
|
|
Also takes the following optional arguments:
|
|
|
|
====================== =====================================================
|
|
Argument Description
|
|
====================== =====================================================
|
|
``max_length`` Ensures the string has at most this many characters.
|
|
``min_length`` Ensures the string has at least this many characters.
|
|
``error_message`` Error message to return for failed validation. If no
|
|
message is provided, a generic error message will be
|
|
used.
|
|
====================== =====================================================
|
|
|
|
``TimeField``
|
|
~~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``None``
|
|
* Normalizes to: A Python ``datetime.time`` object.
|
|
* Validates that the given value is either a ``datetime.time`` or string
|
|
formatted in a particular time format.
|
|
|
|
Takes one optional argument, ``input_formats``, which is a list of formats used
|
|
to attempt to convert a string to a valid ``datetime.time`` object.
|
|
|
|
If no ``input_formats`` argument is provided, the default input formats are::
|
|
|
|
'%H:%M:%S', # '14:30:59'
|
|
'%H:%M', # '14:30'
|
|
|
|
``URLField``
|
|
~~~~~~~~~~~~
|
|
|
|
* Default widget: ``TextInput``
|
|
* Empty value: ``''`` (an empty string)
|
|
* Normalizes to: A Unicode object.
|
|
* Validates that the given value is a valid URL.
|
|
|
|
Takes the following optional arguments:
|
|
|
|
======================== =====================================================
|
|
Argument Description
|
|
======================== =====================================================
|
|
``max_length`` Ensures the string has at most this many characters.
|
|
``min_length`` Ensures the string has at least this many characters.
|
|
``verify_exists`` If ``True``, the validator will attempt to load the
|
|
given URL, raising ``ValidationError`` if the page
|
|
gives a 404. Defaults to ``False``.
|
|
``validator_user_agent`` String used as the user-agent used when checking for
|
|
a URL's existence. Defaults to the value of the
|
|
``URL_VALIDATOR_USER_AGENT`` setting.
|
|
======================== =====================================================
|
|
|
|
Slightly complex built-in ``Field`` classes
|
|
-------------------------------------------
|
|
|
|
The following are not yet documented here. See the unit tests, linked-to from
|
|
the bottom of this document, for examples of their use.
|
|
|
|
``ComboField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
``MultiValueField``
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
``SplitDateTimeField``
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Creating custom fields
|
|
----------------------
|
|
|
|
If the built-in ``Field`` classes don't meet your needs, you can easily create
|
|
custom ``Field`` classes. To do this, just create a subclass of
|
|
``django.newforms.Field``. Its only requirements are that it implement a
|
|
``clean()`` method and that its ``__init__()`` method accept the core arguments
|
|
mentioned above (``required``, ``label``, ``initial``, ``widget``,
|
|
``help_text``).
|
|
|
|
Generating forms for models
|
|
===========================
|
|
|
|
If you're building a database-driven app, chances are you'll have forms that
|
|
map closely to Django models. For instance, you might have a ``BlogComment``
|
|
model, and you want to create a form that lets people submit comments. In this
|
|
case, it would be redundant to define the field types in your form, because
|
|
you've already defined the fields in your model.
|
|
|
|
For this reason, Django provides a few helper functions that let you create a
|
|
``Form`` class from a Django model.
|
|
|
|
``form_for_model()``
|
|
--------------------
|
|
|
|
The method ``django.newforms.form_for_model()`` creates a form based on the
|
|
definition of a specific model. Pass it the model class, and it will return a
|
|
``Form`` class that contains a form field for each model field.
|
|
|
|
For example::
|
|
|
|
>>> from django.newforms import form_for_model
|
|
|
|
# Create the form class.
|
|
>>> ArticleForm = form_for_model(Article)
|
|
|
|
# Create an empty form instance.
|
|
>>> f = ArticleForm()
|
|
|
|
It bears repeating that ``form_for_model()`` takes the model *class*, not a
|
|
model instance, and it returns a ``Form`` *class*, not a ``Form`` instance.
|
|
|
|
Field types
|
|
~~~~~~~~~~~
|
|
|
|
The generated ``Form`` class will have a form field for every model field. Each
|
|
model field has a corresponding default form field. For example, a
|
|
``CharField`` on a model is represented as a ``CharField`` on a form. A
|
|
model ``ManyToManyField`` is represented as a ``MultipleChoiceField``. Here is
|
|
the full list of conversions:
|
|
|
|
=============================== ========================================
|
|
Model field Form field
|
|
=============================== ========================================
|
|
``AutoField`` Not represented in the form
|
|
``BooleanField`` ``BooleanField``
|
|
``CharField`` ``CharField`` with ``max_length`` set to
|
|
the model field's ``maxlength``
|
|
``CommaSeparatedIntegerField`` ``CharField``
|
|
``DateField`` ``DateField``
|
|
``DateTimeField`` ``DateTimeField``
|
|
``EmailField`` ``EmailField``
|
|
``FileField`` ``CharField``
|
|
``FilePathField`` ``CharField``
|
|
``FloatField`` ``CharField``
|
|
``ForeignKey`` ``ModelChoiceField`` (see below)
|
|
``ImageField`` ``CharField``
|
|
``IntegerField`` ``IntegerField``
|
|
``IPAddressField`` ``CharField``
|
|
``ManyToManyField`` ``ModelMultipleChoiceField`` (see
|
|
below)
|
|
``NullBooleanField`` ``CharField``
|
|
``PhoneNumberField`` ``USPhoneNumberField``
|
|
(from ``django.contrib.localflavor.us``)
|
|
``PositiveIntegerField`` ``IntegerField``
|
|
``PositiveSmallIntegerField`` ``IntegerField``
|
|
``SlugField`` ``CharField``
|
|
``SmallIntegerField`` ``IntegerField``
|
|
``TextField`` ``CharField`` with ``widget=Textarea``
|
|
``TimeField`` ``TimeField``
|
|
``URLField`` ``URLField`` with ``verify_exists`` set
|
|
to the model field's ``verify_exists``
|
|
``USStateField`` ``CharField`` with
|
|
``widget=USStateSelect``
|
|
(``USStateSelect`` is from
|
|
``django.contrib.localflavor.us``)
|
|
``XMLField`` ``CharField`` with ``widget=Textarea``
|
|
=============================== ========================================
|
|
|
|
As you might expect, the ``ForeignKey`` and ``ManyToManyField`` model field
|
|
types are special cases:
|
|
|
|
* ``ForeignKey`` is represented by ``django.newforms.ModelChoiceField``,
|
|
which is a ``ChoiceField`` whose choices are a model ``QuerySet``.
|
|
|
|
* ``ManyToManyField`` is represented by
|
|
``django.newforms.ModelMultipleChoiceField``, which is a
|
|
``MultipleChoiceField`` whose choices are a model ``QuerySet``.
|
|
|
|
In addition, each generated form field has attributes set as follows:
|
|
|
|
* If the model field has ``blank=True``, then ``required`` is set to
|
|
``False`` on the form field. Otherwise, ``required=True``.
|
|
|
|
* The form field's ``label`` is set to the ``verbose_name`` of the model
|
|
field, with the first character capitalized.
|
|
|
|
* The form field's ``help_text`` is set to the ``help_text`` of the model
|
|
field.
|
|
|
|
* If the model field has ``choices`` set, then the form field's ``widget``
|
|
will be set to ``Select``, with choices coming from the model field's
|
|
``choices``.
|
|
|
|
Finally, note that you can override the form field used for a given model
|
|
field. See "Overriding the default field types" below.
|
|
|
|
A full example
|
|
~~~~~~~~~~~~~~
|
|
|
|
Consider this set of models::
|
|
|
|
from django.db import models
|
|
|
|
TITLE_CHOICES = (
|
|
('MR', 'Mr.'),
|
|
('MRS', 'Mrs.'),
|
|
('MS', 'Ms.'),
|
|
)
|
|
|
|
class Author(models.Model):
|
|
name = models.CharField(maxlength=100)
|
|
title = models.CharField(maxlength=3, choices=TITLE_CHOICES)
|
|
birth_date = models.DateField(blank=True, null=True)
|
|
|
|
def __str__(self):
|
|
return self.name
|
|
|
|
class Book(models.Model):
|
|
name = models.CharField(maxlength=100)
|
|
authors = models.ManyToManyField(Author)
|
|
|
|
With these models, a call to ``form_for_model(Author)`` would return a ``Form``
|
|
class equivalent to this::
|
|
|
|
class AuthorForm(forms.Form):
|
|
name = forms.CharField(max_length=100)
|
|
title = forms.CharField(max_length=3,
|
|
widget=forms.Select(choices=TITLE_CHOICES))
|
|
birth_date = forms.DateField(required=False)
|
|
|
|
A call to ``form_for_model(Book)`` would return a ``Form`` class equivalent to
|
|
this::
|
|
|
|
class BookForm(forms.Form):
|
|
name = forms.CharField(max_length=100)
|
|
authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())
|
|
|
|
The ``save()`` method
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Every form produced by ``form_for_model()`` also has a ``save()`` method. This
|
|
method creates and saves a database object from the data bound to the form. For
|
|
example::
|
|
|
|
# Create a form instance from POST data.
|
|
>>> f = ArticleForm(request.POST)
|
|
|
|
# Save a new Article object from the form's data.
|
|
>>> new_article = f.save()
|
|
|
|
Note that ``save()`` will raise a ``ValueError`` if the data in the form
|
|
doesn't validate -- i.e., ``if form.errors``.
|
|
|
|
Using an alternate base class
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you want to add custom methods to the form generated by
|
|
``form_for_model()``, write a class that extends ``django.newforms.BaseForm``
|
|
and contains your custom methods. Then, use the ``form`` argument to
|
|
``form_for_model()`` to tell it to use your custom form as its base class.
|
|
For example::
|
|
|
|
# Create the new base class.
|
|
>>> class MyBase(BaseForm):
|
|
... def my_method(self):
|
|
... # Do whatever the method does
|
|
|
|
# Create the form class with a different base class.
|
|
>>> ArticleForm = form_for_model(Article, form=MyBase)
|
|
|
|
# Instantiate the form.
|
|
>>> f = ArticleForm()
|
|
|
|
# Use the base class method.
|
|
>>> f.my_method()
|
|
|
|
Using a subset of fields on the form
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
In some cases, you may not want all the model fields to appear on the generated
|
|
form. There are two ways of telling ``form_for_model()`` to use only a subset
|
|
of the model fields:
|
|
|
|
1. Set ``editable=False`` on the model field. As a result, *any* form
|
|
created from the model via ``form_for_model()`` will not include that
|
|
field.
|
|
|
|
2. Use the ``fields`` argument to ``form_for_model()``. This argument, if
|
|
given, should be a list of field names to include in the form.
|
|
|
|
For example, if you want a form for the ``Author`` model (defined above)
|
|
that includes only the ``name`` and ``title`` fields, you would specify
|
|
``fields`` like this::
|
|
|
|
PartialArticleForm = form_for_model(Author, fields=('name', 'title'))
|
|
|
|
.. note::
|
|
|
|
If you specify ``fields`` when creating a form with ``form_for_model()``,
|
|
make sure that the fields that are *not* specified can provide default
|
|
values, or are allowed to have a value of ``None``. If a field isn't
|
|
specified on a form, the object created from the form can't provide
|
|
a value for that attribute, which will prevent the new instance from
|
|
being saved.
|
|
|
|
Overriding the default field types
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The default field types, as described in the "Field types" table above, are
|
|
sensible defaults; if you have a ``DateField`` in your model, chances are you'd
|
|
want that to be represented as a ``DateField`` in your form. But
|
|
``form_for_model()`` gives you the flexibility of changing the form field type
|
|
for a given model field. You do this by specifying a **formfield callback**.
|
|
|
|
A formfield callback is a function that, when provided with a model field,
|
|
returns a form field instance. When constructing a form, ``form_for_model()``
|
|
asks the formfield callback to provide form field types.
|
|
|
|
By default, ``form_for_model()`` calls the ``formfield()`` method on the model
|
|
field::
|
|
|
|
def default_callback(field, **kwargs):
|
|
return field.formfield(**kwargs)
|
|
|
|
The ``kwargs`` are any keyword arguments that might be passed to the form
|
|
field, such as ``required=True`` or ``label='Foo'``.
|
|
|
|
For example, if you wanted to use ``MyDateFormField`` for any ``DateField``
|
|
field on the model, you could define the callback::
|
|
|
|
>>> def my_callback(field, **kwargs):
|
|
... if isinstance(field, models.DateField):
|
|
... return MyDateFormField(**kwargs)
|
|
... else:
|
|
... return field.formfield(**kwargs)
|
|
|
|
>>> ArticleForm = form_for_model(formfield_callback=my_callback)
|
|
|
|
Note that your callback needs to handle *all* possible model field types, not
|
|
just the ones that you want to behave differently to the default. That's why
|
|
this example has an ``else`` clause that implements the default behavior.
|
|
|
|
Finding the model associated with a form
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The model class that was used to construct the form is available
|
|
using the ``_model`` property of the generated form::
|
|
|
|
>>> ArticleForm = form_for_model(Article)
|
|
>>> ArticleForm._model
|
|
<class 'myapp.models.Article'>
|
|
|
|
``form_for_instance()``
|
|
-----------------------
|
|
|
|
``form_for_instance()`` is like ``form_for_model()``, but it takes a model
|
|
instance instead of a model class::
|
|
|
|
# Create an Author.
|
|
>>> a = Author(name='Joe Smith', title='MR', birth_date=None)
|
|
>>> a.save()
|
|
|
|
# Create a form for this particular Author.
|
|
>>> AuthorForm = form_for_instance(a)
|
|
|
|
# Instantiate the form.
|
|
>>> f = AuthorForm()
|
|
|
|
When a form created by ``form_for_instance()`` is created, the initial
|
|
data values for the form fields are drawn from the instance. However,
|
|
this data is not bound to the form. You will need to bind data to the
|
|
form before the form can be saved.
|
|
|
|
When you call ``save()`` on a form created by ``form_for_instance()``,
|
|
the database instance will be updated. As in ``form_for_model()``, ``save()``
|
|
will raise ``ValueError`` if the data doesn't validate.
|
|
|
|
``form_for_instance()`` has ``form``, ``fields`` and ``formfield_callback``
|
|
arguments that behave the same way as they do for ``form_for_model()``.
|
|
|
|
When should you use ``form_for_model()`` and ``form_for_instance()``?
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``form_for_model()`` and ``form_for_instance()`` functions are meant to be
|
|
shortcuts for the common case. If you want to create a form whose fields map to
|
|
more than one model, or a form that contains fields that *aren't* on a model,
|
|
you shouldn't use these shortcuts. Creating a ``Form`` class the "long" way
|
|
isn't that difficult, after all.
|
|
|
|
More coming soon
|
|
================
|
|
|
|
That's all the documentation for now. For more, see the file
|
|
http://code.djangoproject.com/browser/django/trunk/tests/regressiontests/forms/tests.py
|
|
-- the unit tests for ``django.newforms``. This can give you a good idea of
|
|
what's possible.
|
|
|
|
If you're really itching to learn and use this library, please be patient.
|
|
We're working hard on finishing both the code and documentation.
|