Remove an extraneous comma that I left behind in [7386], and clean up the wording...

[django.git] / docs / newforms.txt

====================
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(required=False)

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** 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.

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 ``cleaned_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.cleaned_data
    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}

.. note::
    **New in Django development version** The ``cleaned_data`` attribute was
    called ``clean_data`` in earlier releases.

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
``cleaned_data`` attribute::

    >>> data = {'subject': '',
    ...         'message': 'Hi there',
    ...         'sender': 'invalid e-mail address',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)
    >>> f.is_valid()
    False
    >>> f.cleaned_data
    Traceback (most recent call last):
    ...
    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'

``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'}

``cleaned_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 ``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 the `Custom form and field
validation`_ section, below.

Behavior of unbound forms
~~~~~~~~~~~~~~~~~~~~~~~~~

It's meaningless to request "cleaned" data in a form with no data, but, for the
record, here's what happens with unbound forms::

    >>> f = ContactForm()
    >>> f.cleaned_data
    Traceback (most recent call last):
    ...
    AttributeError: 'ContactForm' object has no attribute 'cleaned_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'``.

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 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>

Customizing the error list format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, forms use ``django.newforms.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.newforms.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 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)
    ''

Using forms in views and templates
----------------------------------

Let's put this all together and use the ``ContactForm`` example in a Django
view and template.

Simple view example
~~~~~~~~~~~~~~~~~~~

This example view displays the contact form by default and validates/processes
it if accessed via a POST request::

    def contact(request):
        if request.method == 'POST':
            form = ContactForm(request.POST)
            if form.is_valid():
                # Do form processing here...
                return HttpResponseRedirect('/url/on_success/')
        else:
            form = ContactForm()
        return render_to_response('contact.html', {'form': form})

Simple template example
~~~~~~~~~~~~~~~~~~~~~~~

The template in the above view example, ``contact.html``, is responsible for
displaying the form as HTML. To do this, we can use the techniques outlined in
the "Outputting forms as HTML" section above.

The simplest way to display a form's HTML is to use the variable on its own,
like this::

    <form method="post" action="">
    <table>{{ form }}</table>
    <input type="submit" />
    </form>

The above template code will display the form as an HTML table, using the
``form.as_table()`` method explained previously. This works because Django's
template system displays an object's ``__str__()`` value, and the ``Form``
class' ``__str__()`` method calls its ``as_table()`` method.

The following is equivalent but a bit more explicit::

    <form method="post" action="">
    <table>{{ form.as_table }}</table>
    <input type="submit" />
    </form>

``form.as_ul`` and ``form.as_p`` are also available, as you may expect.

Note that in the above two examples, we included the ``<form>``, ``<table>``
``<input type="submit" />``, ``</table>`` and ``</form>`` tags. The form
convenience methods (``as_table()``, ``as_ul()`` and ``as_p()``) do not include
that HTML.

Complex template output
~~~~~~~~~~~~~~~~~~~~~~~

As we've stressed several times, the ``as_table()``, ``as_ul()`` and ``as_p()``
methods are just shortcuts for the common case. You can also work with the
individual fields for complete template control over the form's design.

The easiest way is to iterate over the form's fields, with
``{% for field in form %}``. For example::

    <form method="post" action="">
    <dl>
    {% for field in form %}
        <dt>{{ field.label_tag }}</dt>
        <dd>{{ field }}</dd>
        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
    {% endfor %}
    </dl>
    <input type="submit" />
    </form>

This iteration technique is useful if you want to apply the same HTML
formatting to each field, or if you don't know the names of the form fields
ahead of time. Note that the fields will be iterated over in the order in which
they're defined in the ``Form`` class.

Alternatively, you can arrange the form's fields explicitly, by name. Do that
by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name.
For example::

    <form method="post" action="">
    <ul class="myformclass">
        <li>{{ form.sender.label_tag }} {{ form.sender }}</li>
        <li class="helptext">{{ form.sender.help_text }}</li>
        {% if form.sender.errors %}<ul class="errorlist">{{ form.sender.errors }}</ul>{% endif %}

        <li>{{ form.subject.label_tag }} {{ form.subject }}</li>
        <li class="helptext">{{ form.subject.help_text }}</li>
        {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</ul>{% endif %}

        ...
    </ul>
    </form>

Highlighting required fields in templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's common to show a user which fields are required. Here's an example of how
to do that, using the above example modified to insert an asterisk after the
label of each required field::

    <form method="post" action="">
    <dl>
    {% for field in form %}
        <dt>{{ field.label_tag }}{% if field.field.required %}*{% endif %}</dt>
        <dd>{{ field }}</dd>
        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
        {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
    {% endfor %}
    </dl>
    <input type="submit" />
    </form>

The ``{% if field.field.required %}*{% endif %}`` fragment is the relevant
addition here. It adds the asterisk only if the field is required.

Note that we check ``field.field.required`` and not ``field.required``. In the
template, ``field`` is a ``newforms.forms.BoundField`` instance, which holds
the actual ``Field`` instance in its ``field`` attribute.

Binding uploaded files to a form
--------------------------------

**New in Django development version**

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
    >>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': 'foo@example.com',
    ...         'cc_myself': True}
    >>> file_data = {'mugshot': {'filename':'face.jpg'
    ...                          'content': <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>

Prefixes for forms
------------------

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>

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(required=False)
    >>> 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>

``error_messages``
~~~~~~~~~~~~~~~~~~

**New in Django development version**

The ``error_messages`` argument lets you override the default messages that the
field will raise. Pass in a dictionary with keys matching the error messages you
want to override. For example, here is the default error message::

    >>> generic = forms.CharField()
    >>> generic.clean('')
    Traceback (most recent call last):
      ...
    ValidationError: [u'This field is required.']

And here is a custom error message::

    >>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
    >>> name.clean('')
    Traceback (most recent call last):
      ...
    ValidationError: [u'Please enter your name']

In the `built-in Field classes`_ section below, each ``Field`` defines the
error message keys it uses.

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: ``False``
    * Normalizes to: A Python ``True`` or ``False`` value.
    * Validates that the check box is checked (i.e. the value is ``True``) if
      the field has ``required=True``.
    * Error message keys: ``required``

**New in Django development version:** The empty value for a ``CheckboxInput``
(and hence the standard ``BooleanField``) has changed to return ``False``
instead of ``None`` in the development version.

.. note::
    Since all ``Field`` subclasses have ``required=True`` by default, the
    validation condition here is important. If you want to include a checkbox
    in your form that can be either checked or unchecked, you must remember to
    pass in ``required=False`` when creating the ``BooleanField``.

``CharField``
~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates ``max_length`` or ``min_length``, if they are provided.
      Otherwise, all inputs are valid.
    * Error message keys: ``required``, ``max_length``, ``min_length``

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.
    * Error message keys: ``required``, ``invalid_choice``

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.
    * Error message keys: ``required``, ``invalid``

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: ``DateTimeInput``
    * 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.
    * Error message keys: ``required``, ``invalid``

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'

**New in Django development version:** The ``DateTimeField`` used to use a
``TextInput`` widget by default. This has now changed.

``DecimalField``
~~~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``TextInput``
    * Empty value: ``None``
    * Normalizes to: A Python ``decimal``.
    * Validates that the given value is a decimal. Leading and trailing
      whitespace is ignored.
    * Error message keys: ``required``, ``invalid``, ``max_value``,
      ``min_value``, ``max_digits``, ``max_decimal_places``,
      ``max_whole_digits``

Takes four optional arguments: ``max_value``, ``min_value``, ``max_digits``,
and ``decimal_places``. The first two define the limits for the fields value.
``max_digits`` is the maximum number of digits (those before the decimal
point plus those after the decimal point, with leading zeros stripped)
permitted in the value, whilst ``decimal_places`` is the maximum number of
decimal places permitted.

``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.
    * Error message keys: ``required``, ``invalid``

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.

``FileField``
~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``FileInput``
    * Empty value: ``None``
    * Normalizes to: An ``UploadedFile`` object that wraps the file content
      and file name into a single object.
    * Validates that non-empty file data has been bound to the form.
    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``

An ``UploadedFile`` object has two attributes:

    ======================  ====================================================
    Attribute               Description
    ======================  ====================================================
    ``filename``            The name of the file, provided by the uploading
                            client.
                            
    ``content``             The array of bytes comprising the file content.
    ======================  ====================================================

The string representation of an ``UploadedFile`` is the same as the filename
attribute.

When you use a ``FileField`` on a form, you must also remember to
`bind the file data to the form`_.

.. _`bind the file data to the form`: `Binding uploaded files to a form`_

``FilePathField``
~~~~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``Select``
    * Empty value: ``None``
    * Normalizes to: A unicode object
    * Validates that the selected choice exists in the list of choices.
    * Error message keys: ``required``, ``invalid_choice``

The field allows choosing from files inside a certain directory. It takes three
extra arguments:

    ==============  ==========  ===============================================
    Argument        Required?   Description
    ==============  ==========  ===============================================
    ``path``        Yes         The absolute path to the directory whose 
                                contents you want listed. This directory must 
                                exist.
                            
    ``recursive``   No          If ``False`` (the default) only the direct
                                contents of ``path`` will be offered as choices.
                                If ``True``, the directory will be descended
                                into recursively and all descendants will be
                                listed as choices.
                                
    ``match``       No          A regular expression pattern; only files with
                                names matching this expression will be allowed
                                as choices.
    ==============  ==========  ===============================================

``ImageField``
~~~~~~~~~~~~~~

**New in Django development version**

    * Default widget: ``FileInput``
    * Empty value: ``None``
    * Normalizes to: An ``UploadedFile`` object that wraps the file content
      and file name into a single object.
    * Validates that file data has been bound to the form, and that the
      file is of an image format understood by PIL.
    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
      ``invalid_image``

Using an ImageField requires that the `Python Imaging Library`_ is installed.

When you use a ``FileField`` on a form, you must also remember to
`bind the file data to the form`_.

.. _Python Imaging Library: http://www.pythonware.com/products/pil/

``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.
    * Error message keys: ``required``, ``invalid``, ``max_value``,
      ``min_value``

Takes two optional arguments for validation, ``max_value`` and ``min_value``.
These control the range of values permitted in the field.

``IPAddressField``
~~~~~~~~~~~~~~~~~~

    * Default widget: ``TextInput``
    * Empty value: ``''`` (an empty string)
    * Normalizes to: A Unicode object.
    * Validates that the given value is a valid IPv4 address, using a regular
      expression.
    * Error message keys: ``required``, ``invalid``

``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.
    * Error message keys: ``required``, ``invalid_choice``, ``invalid_list``

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.
    * Error message keys: ``required``, ``invalid``

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.
    ======================  =====================================================

The optional argument ``error_message`` is also accepted for backwards
compatibility. The preferred way to provide an error message is to use the
``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key
and the error message as the value.

``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.
    * Error message keys: ``required``, ``invalid``

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.
    * Error message keys: ``required``, ``invalid``, ``invalid_link``

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``
~~~~~~~~~~~~~~~~~~~~~~

Fields which handle relationships
---------------------------------

For representing relationships between models, two fields are
provided which can derive their choices from a ``QuerySet``, and which
place one or more model objects into the ``cleaned_data`` dictionary
of forms in which they're used. Both of these fields have an
additional required argument:

``queryset``
    A ``QuerySet`` of model objects from which the choices for the
    field will be derived, and which will be used to validate the
    user's selection.

``ModelChoiceField``
~~~~~~~~~~~~~~~~~~~~

Allows the selection of a single model object, suitable for
representing a foreign key.

The ``__unicode__`` method of the model will be called to generate
string representations of the objects for use in the field's choices;
to provide customized representations, subclass ``ModelChoiceField``
and override ``label_for_model``. This method will receive model
object, and should return a string suitable for representing it::

    class MyModelChoiceField(ModelChoiceField):
        def label_from_instance(self, obj):
            return "My Object #%i" % obj.id

``ModelMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Allows the selection of one or more model objects, suitable for
representing a many-to-many relation. As with ``ModelChoiceField``,
you can use ``label_from_instance`` to customize the object
representations.

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``).

Custom form and field validation
---------------------------------

Form validation happens when the data is cleaned. If you want to customise
this process, there are various places you can change, each one serving a
different purpose. Three types of cleaning methods are run during form
processing. These are normally executed when you call the ``is_valid()``
method on a form. There are other things that can trigger cleaning and
validation (accessing the ``errors`` attribute or calling ``full_clean()``
directly), but normally they won't be needed.

In general, any cleaning method can raise ``ValidationError`` if there is a
problem with the data it is processing, passing the relevant error message to
the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the
method should return the cleaned (normalised) data as a Python object.

If you detect multiple errors during a cleaning method and wish to signal all
of them to the form submitter, it is possible to pass a list of errors to the
``ValidationError`` constructor.

The three types of cleaning methods are:

    * The ``clean()`` method on a Field subclass. This is responsible
      for cleaning the data in a way that is generic for that type of field.
      For example, a FloatField will turn the data into a Python ``float`` or
      raise a ``ValidationError``.

    * The ``clean_<fieldname>()`` method in a form subclass -- where
      ``<fieldname>`` is replaced with the name of the form field attribute.
      This method does any cleaning that is specific to that particular
      attribute, unrelated to the type of field that it is. This method is not
      passed any parameters. You will need to look up the value of the field
      in ``self.cleaned_data`` and remember that it will be a Python object
      at this point, not the original string submitted in the form (it will be
      in ``cleaned_data`` because the general field ``clean()`` method, above,
      has already cleaned the data once).

      For example, if you wanted to validate that the contents of a
      ``CharField`` called ``serialnumber`` was unique,
      ``clean_serialnumber()`` would be the right place to do this. You don't
      need a specific field (it's just a ``CharField``), but you want a
      formfield-specific piece of validation and, possibly,
      cleaning/normalizing the data.

    * The Form subclass's ``clean()`` method. This method can perform
      any validation that requires access to multiple fields from the form at
      once. This is where you might put in things to check that if field ``A``
      is supplied, field ``B`` must contain a valid email address and the
      like. The data that this method returns is the final ``cleaned_data``
      attribute for the form, so don't forget to return the full list of
      cleaned data if you override this method (by default, ``Form.clean()``
      just returns ``self.cleaned_data``).

      Note that any errors raised by your ``Form.clean()`` override will not
      be associated with any field in particular. They go into a special
      "field" (called ``__all__``), which you can access via the
      ``non_field_errors()`` method if you need to.

These methods are run in the order given above, one field at a time.  That is,
for each field in the form (in the order they are declared in the form
definition), the ``Field.clean()`` method (or its override) is run, then
``clean_<fieldname>()``. Finally, once those two methods are run for every
field, the ``Form.clean()`` method, or its override, is executed.

As mentioned above, any of these methods can raise a ``ValidationError``. For
any field, if the ``Field.clean()`` method raises a ``ValidationError``, any
field-specific cleaning method is not called. However, the cleaning methods
for all remaining fields are still executed.

The ``clean()`` method for the ``Form`` class or subclass is always run. If
that method raises a ``ValidationError``, ``cleaned_data`` will be an empty
dictionary.

The previous paragraph means that if you are overriding ``Form.clean()``, you
should iterate through ``self.cleaned_data.items()``, possibly considering the
``_errors`` dictionary attribute on the form as well. In this way, you will
already know which fields have passed their individual validation requirements.

A simple example
~~~~~~~~~~~~~~~~

Here's a simple example of a custom field that validates its input is a string
containing comma-separated e-mail addresses, with at least one address. We'll
keep it simple and assume e-mail validation is contained in a function called
``is_valid_email()``. The full class::

    from django import newforms as forms

    class MultiEmailField(forms.Field):
        def clean(self, value):
            if not value:
                raise forms.ValidationError('Enter at least one e-mail address.')
            emails = value.split(',')
            for email in emails:
                if not is_valid_email(email):
                    raise forms.ValidationError('%s is not a valid e-mail address.' % email)
            return emails

Let's alter the ongoing ``ContactForm`` example to demonstrate how you'd use
this in a form. Simply use ``MultiEmailField`` instead of ``forms.EmailField``,
like so::

    class ContactForm(forms.Form):
        subject = forms.CharField(max_length=100)
        message = forms.CharField()
        senders = MultiEmailField()
        cc_myself = forms.BooleanField(required=False)

Widgets
=======

A widget is Django's representation of a HTML input element. The widget
handles the rendering of the HTML, and the extraction of data from a GET/POST
dictionary that corresponds to the widget.

Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets:

    ============================  ===========================================
    Widget                        HTML Equivalent
    ============================  ===========================================
    ``TextInput``                 ``<input type='text' ...``
    ``PasswordInput``             ``<input type='password' ...``
    ``HiddenInput``               ``<input type='hidden' ...``
    ``MultipleHiddenInput``       Multiple ``<input type='hidden' ...``
                                  instances.
    ``FileInput``                 ``<input type='file' ...``
    ``DateTimeInput``             ``<input type='text' ...``
    ``Textarea``                  ``<textarea>...</textarea>``
    ``CheckboxInput``             ``<input type='checkbox' ...``
    ``Select``                    ``<select><option ...``
    ``NullBooleanSelect``         Select widget with options 'Unknown',
                                  'Yes' and 'No'
    ``SelectMultiple``            ``<select multiple='multiple'><option ...``
    ``RadioSelect``               ``<ul><li><input type='radio' ...``
    ``CheckboxSelectMultiple``    ``<ul><li><input type='checkbox' ...``
    ``MultiWidget``               Wrapper around multiple other widgets
    ``SplitDateTimeWidget``       Wrapper around two ``TextInput`` widgets:
                                  one for the Date, and one for the Time.
    ============================  ===========================================

**New in Django development version:** The ``DateTimeInput`` has been added
since the last release.

Specifying widgets
------------------

Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find
which widget is used on which field, see the documentation for the
built-in Field classes.

However, if you want to use a different widget for a field, you can -
just use the 'widget' argument on the field definition. For example::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField(widget=forms.Textarea)

This would specify a form with a comment that uses a larger Textarea widget,
rather than the default TextInput widget.

Customizing widget instances
----------------------------

When Django renders a widget as HTML, it only renders the bare minimum
HTML - Django doesn't add a class definition, or any other widget-specific
attributes. This means that all 'TextInput' widgets will appear the same
on your web page.

If you want to make one widget look different to another, you need to
specify additional attributes for each widget. When you specify a
widget, you can provide a list of attributes that will be added to the
rendered HTML for the widget.

For example, take the following simple form::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField()

This form will include three default TextInput widgets, with default rendering -
no CSS class, no extra attributes. This means that the input boxes provided for
each widget will be rendered exactly the same::

    >>> f = CommentForm(auto_id=False)
    >>> f.as_table()
    <tr><th>Name:</th><td><input type="text" name="name" /></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>

On a real web page, you probably don't want every widget to look the same. You
might want a larger input element for the comment, and you might want the
'name' widget to have some special CSS class. To do this, you specify a
custom widget for your fields, and specify some attributes to use
when rendering those widgets::

    class CommentForm(forms.Form):
        name = forms.CharField(
                    widget=forms.TextInput(attrs={'class':'special'}))
        url = forms.URLField()
        comment = forms.CharField(
                   widget=forms.TextInput(attrs={'size':'40'}))

Django will then include the extra attributes in the rendered output::

    >>> f = CommentForm(auto_id=False)
    >>> f.as_table()
    <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>

Custom Widgets
--------------

When you start to write a lot of forms, you will probably find that you will
reuse certain sets of widget attributes over and over again. Rather than
repeat these attribute definitions every time you need them, Django allows
you to capture those definitions as a custom widget.

For example, if you find that you are including a lot of comment fields on forms,
you could capture the idea of a ``TextInput`` with a specific ``size`` attribute
as a custom extension to the ``TextInput`` widget::

    class CommentWidget(forms.TextInput):
        def __init__(self, *args, **kwargs):
            kwargs.setdefault('attrs',{}).update({'size': '40'})
            super(CommentWidget, self).__init__(*args, **kwargs)

Then you can use this widget in your forms::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField(widget=CommentWidget)

You can even customize your custom widget, in the same way as you would
any other widget. Adding a once-off class to your ``CommentWidget`` is as
simple as adding an attribute definition::

    class CommentForm(forms.Form):
        name = forms.CharField(max_length=20)
        url = forms.URLField()
        comment = forms.CharField(
                    widget=CommentWidget(attrs={'class': 'special'}))

Django also makes it easy to specify a custom field type that uses your custom
widget. For example, you could define a customized field type for comments
by defining::

    class CommentInput(forms.CharField):
        widget = CommentWidget

You can then use this field whenever you have a form that requires a comment::

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = CommentInput()

Generating forms for models
===========================

The prefered way of generating forms that work with models is explained in the
`ModelForms documentation`_.

Looking for the ``form_for_model`` and ``form_for_instance`` documentation?
They've been deprecated, but you can still `view the documentation`_.

.. _ModelForms documentation: ../modelforms/
.. _view the documentation: ../form_for_model/

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
-- the unit tests for ``django.newforms``. This can give you a good idea of
what's possible. (Each submodule there contains separate tests.)

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.