--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/ref/forms/fields.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,939 @@
+===========
+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
+
+.. 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 <binding-uploaded-files>`.
+
+.. _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.
+
+``SlugField``
+~~~~~~~~~~~~~
+
+.. class:: SlugField(**kwargs)
+
+ * Default widget: ``TextInput``
+ * Empty value: ``''`` (an empty string)
+ * Normalizes to: A Unicode object.
+ * Validates that the given value contains only letters, numbers,
+ underscores, and hyphens.
+ * Error messages: ``required``, ``invalid``
+
+This field is intended for use in representing a model
+:class:`~django.db.models.SlugField` in forms.
+
+``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.
+
+.. versionchanged:: 1.2
+ The URLField previously did not recognize URLs as valid that contained an IDN
+ (Internationalized Domain Name; a domain name containing unicode characters)
+ domain name. This has now been corrected.
+
+
+Slightly complex built-in ``Field`` classes
+-------------------------------------------
+
+``ComboField``
+~~~~~~~~~~~~~~
+
+.. class:: ComboField(**kwargs)
+
+ * Default widget: ``TextInput``
+ * Empty value: ``''`` (an empty string)
+ * Normalizes to: A Unicode object.
+ * Validates that the given value against each of the fields specified
+ as an argument to the ``ComboField``.
+ * Error message keys: ``required``, ``invalid``
+
+Takes one extra required argument:
+
+.. attribute:: ComboField.fields
+
+ The list of fields that should be used to validate the field's value (in
+ the order in which they are provided).
+
+ >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
+ >>> f.clean('test@example.com')
+ u'test@example.com'
+ >>> f.clean('longemailaddress@example.com')
+ Traceback (most recent call last):
+ ...
+ ValidationError: [u'Ensure this value has at most 20 characters (it has 28).']
+
+``MultiValueField``
+~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultiValueField(**kwargs)
+
+ * Default widget: ``TextInput``
+ * Empty value: ``''`` (an empty string)
+ * Normalizes to: the type returned by the ``compress`` method of the subclass.
+ * Validates that the given value against each of the fields specified
+ as an argument to the ``MultiValueField``.
+ * Error message keys: ``required``, ``invalid``
+
+ This abstract field (must be subclassed) aggregates the logic of multiple
+ fields. Subclasses should not have to implement clean(). Instead, they must
+ implement compress(), which takes a list of valid values and returns a
+ "compressed" version of those values -- a single value. For example,
+ :class:`SplitDateTimeField` is a subclass which combines a time field and
+ a date field into a datetime object.
+
+Takes one extra required argument:
+
+.. attribute:: MultiValueField.fields
+
+ A list of fields which are cleaned into a single field. Each value in
+ ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
+ value is cleaned by the first field, the second value is cleaned by
+ the second field, etc. Once all fields are cleaned, the list of clean
+ values is "compressed" into a single value.
+
+``SplitDateTimeField``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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
+---------------------------------
+
+Two fields are available for representing relationships between
+models: :class:`ModelChoiceField` and
+:class:`ModelMultipleChoiceField`. Both of these fields require a
+single ``queryset`` parameter that is used to create the choices for
+the field. Upon form validation, these fields will place either one
+model object (in the case of ``ModelChoiceField``) or multiple model
+objects (in the case of ``ModelMultipleChoiceField``) into the
+``cleaned_data`` dictionary of the form.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: ModelChoiceField(**kwargs)
+
+ * Default widget: ``Select``
+ * Empty value: ``None``
+ * Normalizes to: A model instance.
+ * Validates that the given id exists in the queryset.
+ * Error message keys: ``required``, ``invalid_choice``
+
+Allows the selection of a single model object, suitable for
+representing a foreign key. A single argument is required:
+
+.. 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`` also takes one optional argument:
+
+.. attribute:: ModelChoiceField.empty_label
+
+ By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
+ an empty choice at the top of the list. You can change the text of this
+ label (which is ``"---------"`` by default) with the ``empty_label``
+ attribute, or you can disable the empty label entirely by setting
+ ``empty_label`` to ``None``::
+
+ # A custom empty label
+ field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
+
+ # No empty label
+ field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+
+ Note that if a ``ModelChoiceField`` is required and has a default
+ initial value, no empty choice is created (regardless of the value
+ of ``empty_label``).
+
+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
+
+``ModelMultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: ModelMultipleChoiceField(**kwargs)
+
+ * Default widget: ``SelectMultiple``
+ * Empty value: ``[]`` (an empty list)
+ * Normalizes to: A list of model instances.
+ * Validates that every id in the given list of values exists in the
+ queryset.
+ * Error message keys: ``required``, ``list``, ``invalid_choice``,
+ ``invalid_pk_value``
+
+Allows the selection of one or more model objects, suitable for
+representing a many-to-many relation. As with :class:`ModelChoiceField`,
+you can use ``label_from_instance`` to customize the object
+representations, and ``queryset`` is a required parameter:
+
+.. attribute:: ModelMultipleChoiceField.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.
+
+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.forms.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``).