===========

Form fields

===========

.. module:: django.forms.fields

   :synopsis: Django's built-in form fields.

.. currentmodule:: django.forms

.. class:: Field(**kwargs)

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.

.. method:: Field.clean(value)

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.forms.ValidationError``

exception or returns the clean value::

    >>> from django import forms

    >>> 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.']

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

~~~~~~~~~~~~

.. attribute:: Field.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``

~~~~~~~~~

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

~~~~~~~~~~~

.. attribute:: Field.initial

The ``initial`` argument lets you specify the initial value to use when

rendering this ``Field`` in an unbound ``Form``.

To specify dynamic initial data, see the :attr:`Form.initial` parameter.

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

Instead of a constant, you can also pass any callable::

    >>> import datetime

    >>> class DateForm(forms.Form):

    ...     day = forms.DateField(initial=datetime.date.today)

    >>> print DateForm()

    <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr>

The callable will be evaluated only when the unbound form is displayed, not when it is defined.

``widget``

~~~~~~~~~~

.. attribute:: Field.widget

The ``widget`` argument lets you specify a ``Widget`` class to use when

rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information.

``help_text``

~~~~~~~~~~~~~

.. attribute:: Field.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``

~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.0

.. attribute:: Field.error_messages

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.

``validators``

~~~~~~~~~~~~~~

.. versionadded:: 1.2

.. attribute:: Field.validators

The ``validators`` argument lets you provide a list of validation functions

for this field.

See the :doc:`validators documentation </ref/validators>` for more information.

``localize``

~~~~~~~~~~~~

.. versionadded:: 1.2

.. attribute:: Field.localize

The ``localize`` argument enables the localization of form data, input as well

as the rendered output.

See the :ref:`format localization <format-localization>` documentation for

more information.

Built-in ``Field`` classes

--------------------------

Naturally, the ``forms`` 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``

~~~~~~~~~~~~~~~~

.. class:: BooleanField(**kwargs)

    * Default widget: ``CheckboxInput``

    * Empty value: ``False``

    * Normalizes to: A Python ``True`` or ``False`` value.

    * Validates that the value is ``True`` (e.g. the check box is checked) if

      the field has ``required=True``.

    * Error message keys: ``required``

.. versionchanged:: 1.0

   The empty value for a ``CheckboxInput`` (and hence the standard

   ``BooleanField``) has changed to return ``False`` instead of ``None`` in

   the Django 1.0.

.. note::

    Since all ``Field`` subclasses have ``required=True`` by default, the

    validation condition here is important. If you want to include a boolean

    in your form that can be either ``True`` or ``False`` (e.g. a checked or

    unchecked checkbox), you must remember to pass in ``required=False`` when

    creating the ``BooleanField``.

``CharField``

~~~~~~~~~~~~~

.. class:: CharField(**kwargs)

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

.. attribute:: CharField.max_length

.. attribute:: CharField.min_length

    If provided, these arguments ensure that the string is at most or at least

    the given length.

``ChoiceField``

~~~~~~~~~~~~~~~

.. class:: ChoiceField(**kwargs)

    * 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 required argument:

.. attribute:: ChoiceField.choices

    An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this

    field. This argument accepts the same formats as the ``choices`` argument

    to a model field. See the :ref:`model field reference documentation on

    choices <field-choices>` for more details.

``TypedChoiceField``

~~~~~~~~~~~~~~~~~~~~

.. class:: TypedChoiceField(**kwargs)

Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes an

extra ``coerce`` argument.

    * Default widget: ``Select``

    * Empty value: Whatever you've given as ``empty_value``

    * Normalizes to: the value returned by the ``coerce`` argument.

    * Validates that the given value exists in the list of choices.

    * Error message keys: ``required``, ``invalid_choice``

Takes extra arguments:

.. attribute:: TypedChoiceField.coerce

    A function that takes one argument and returns a coerced value. Examples

    include the built-in ``int``, ``float``, ``bool`` and other types. Defaults

    to an identity function.

.. attribute:: TypedChoiceField.empty_value

    The value to use to represent "empty." Defaults to the empty string;

    ``None`` is another common choice here.

``DateField``

~~~~~~~~~~~~~

.. class:: DateField(**kwargs)

    * Default widget: ``DateInput``

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

.. attribute:: DateField.input_formats

    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'

.. versionchanged:: 1.1

   The ``DateField`` previously used a ``TextInput`` widget by default. It now

   uses a ``DateInput`` widget.

``DateTimeField``

~~~~~~~~~~~~~~~~~

.. class:: DateTimeField(**kwargs)

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

.. attribute:: DateTimeField.input_formats

    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'

.. versionchanged:: 1.0

   The ``DateTimeField`` used to use a ``TextInput`` widget by default. This has now changed.

``DecimalField``

~~~~~~~~~~~~~~~~

.. versionadded:: 1.0

.. class:: DecimalField(**kwargs)

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

.. attribute:: DecimalField.max_value

.. attribute:: DecimalField.min_value

    These attributes define the limits for the fields value.

.. attribute:: DecimalField.max_digits

    The maximum number of digits (those before the decimal point plus those

    after the decimal point, with leading zeros stripped) permitted in the

    value.

.. attribute:: DecimalField.decimal_places

    The maximum number of decimal places permitted.

``EmailField``

~~~~~~~~~~~~~~

.. class:: EmailField(**kwargs)

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

.. versionchanged:: 1.2

   The EmailField previously did not recognize e-mail addresses as valid that

   contained an IDN (Internationalized Domain Name; a domain containing

   unicode characters) domain part. This has now been corrected.

``FileField``

~~~~~~~~~~~~~

.. versionadded:: 1.0

.. class:: FileField(**kwargs)

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

To learn more about the ``UploadedFile`` object, see the :doc:`file uploads

documentation </topics/http/file-uploads>`.

When you use a ``FileField`` in a form, you must also remember to

:ref:`bind the file data to the form <binding-uploaded-files>`.

``FilePathField``

~~~~~~~~~~~~~~~~~

.. versionadded:: 1.0