.. _ref-forms-fields: =========== 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 Your name: Your Web site: Comment: ``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 Name: Url: Comment: 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 Name: Url: Comment: 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() Day: 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 :ref:`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() Subject:
100 characters max. Message: Sender:
A valid e-mail address, please. Cc myself: >>> print f.as_ul()
  • Subject: 100 characters max.
  • Message:
  • Sender: A valid e-mail address, please.
  • Cc myself:
    • >>> print f.as_p()

    Subject: 100 characters max.

    Message:

    Sender: A valid e-mail address, please.

    Cc myself:

    ``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. 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. ``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. ``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 :ref:`file uploads documentation `. When you use a ``FileField`` in a form, you must also remember to :ref:`bind the file data to the form `. ``FilePathField`` ~~~~~~~~~~~~~~~~~ .. versionadded:: 1.0 .. class:: FilePathField(**kwargs) * 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; only ``path`` is required: .. attribute:: FilePathField.path The absolute path to the directory whose contents you want listed. This directory must exist. .. attribute:: FilePathField.recursive 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. .. attribute:: FilePathField.match A regular expression pattern; only files with names matching this expression will be allowed as choices. ``FloatField`` ~~~~~~~~~~~~~~ * Default widget: ``TextInput`` * Empty value: ``None`` * Normalizes to: A Python float. * Validates that the given value is an float. Leading and trailing whitespace is allowed, as in Python's ``float()`` 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. ``ImageField`` ~~~~~~~~~~~~~~ .. versionadded:: 1.0 .. class:: ImageField(**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 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 an ``ImageField`` on a form, you must also remember to :ref:`bind the file data to the form `. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ ``IntegerField`` ~~~~~~~~~~~~~~~~ .. class:: IntegerField(**kwargs) * 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: .. attribute:: IntegerField.max_value .. attribute:: IntegerField.min_value These control the range of values permitted in the field. ``IPAddressField`` ~~~~~~~~~~~~~~~~~~ .. class:: IPAddressField(**kwargs) * 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`` ~~~~~~~~~~~~~~~~~~~~~~~ .. class:: MultipleChoiceField(**kwargs) * 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``, as for ``ChoiceField``. ``NullBooleanField`` ~~~~~~~~~~~~~~~~~~~~ .. class:: NullBooleanField(**kwargs) * 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`` ~~~~~~~~~~~~~~ .. class:: RegexField(**kwargs) * 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: .. attribute:: RegexField.regex A regular expression specified either as a string or a compiled regular expression object. Also takes ``max_length`` and ``min_length``, which work just as they do for ``CharField``. 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`` ~~~~~~~~~~~~~ .. class:: TimeField(**kwargs) * 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: .. attribute:: TimeField.input_formats 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`` ~~~~~~~~~~~~ .. class:: URLField(**kwargs) * 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: .. attribute:: URLField.max_length .. attribute:: URLField.min_length Same as ``CharField.max_length`` and ``CharField.min_length``. .. attribute:: URLField.verify_exists If ``True``, the validator will attempt to load the given URL, raising ``ValidationError`` if the page gives a 404. Defaults to ``False``. .. attribute:: URLField.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. .. class:: ComboField(**kwargs) .. class:: MultiValueField(**kwargs) .. class:: SplitDateTimeField(**kwargs) * Default widget: ``SplitDateTimeWidget`` * Empty value: ``None`` * Normalizes to: A Python ``datetime.datetime`` object. * Validates that the given value is a ``datetime.datetime`` or string formatted in a particular datetime format. * Error message keys: ``required``, ``invalid`` Takes two optional arguments: .. attribute:: SplitDateTimeField.input_date_formats A list of formats used to attempt to convert a string to a valid ``datetime.date`` object. If no ``input_date_formats`` argument is provided, the default input formats for ``DateField`` are used. .. attribute:: SplitDateTimeField.input_time_formats A list of formats used to attempt to convert a string to a valid ``datetime.time`` object. If no ``input_time_formats`` argument is provided, the default input formats for ``TimeField`` are used. .. versionchanged:: 1.1 The ``SplitDateTimeField`` previously used two ``TextInput`` widgets by default. The ``input_date_formats`` and ``input_time_formats`` arguments are also new. Fields which handle relationships --------------------------------- For representing relationships between models, two fields are provided which can derive their choices from a ``QuerySet``: .. class:: ModelChoiceField(**kwargs) .. class:: ModelMultipleChoiceField(**kwargs) These fields 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: .. attribute:: ModelChoiceField.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_from_instance``. This method will receive a model object, and should return a string suitable for representing it. For example:: class MyModelChoiceField(ModelChoiceField): def label_from_instance(self, obj): return "My Object #%i" % obj.id .. attribute:: ModelChoiceField.empty_label By default the ``