====================
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 the ``django.newforms`` package to ``django.forms``
in the future. The current ``django.forms`` package will be available as
``django.oldforms``.

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 ``Form`` attribute ``errors`` 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``.

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

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``
``'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>`` 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>`` 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 available:

``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 in a ``Form``.

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>

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.