Fixed #3780 -- Added first stab at 'Built-in Field classes' section to docs/newforms.txt, with help from SmileyChris and Marc Fargas

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5222 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2007-05-14 05:32:35 +00:00
parent 0810919694
commit 70703a6b71
1 changed files with 217 additions and 8 deletions

View File

@ -481,7 +481,7 @@ field::
If ``auto_id`` is set to a string containing the format character ``'%s'``, 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`` then the form output will include ``<label>`` tags, and will generate ``id``
attributes based on the format string. For example, for a format string attributes based on the format string. For example, for a format string
``'field_%s'``, a field named ``subject`` will get the ``id`` ``'field_%s'``, a field named ``subject`` will get the ``id`` value
``'field_subject'``. Continuing our example:: ``'field_subject'``. Continuing our example::
>>> f = ContactForm(auto_id='id_for_%s') >>> f = ContactForm(auto_id='id_for_%s')
@ -520,8 +520,9 @@ How errors are displayed
If you render a bound ``Form`` object, the act of rendering will automatically 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 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 will include the validation errors as a ``<ul class="errorlist">`` near the
positioning of the error messages depends on the output method you're using:: field. The particular positioning of the error messages depends on the output
method you're using::
>>> data = {'subject': '', >>> data = {'subject': '',
... 'message': 'Hi there', ... 'message': 'Hi there',
@ -583,7 +584,8 @@ The field-specific output honors the form object's ``auto_id`` setting::
<input type="text" name="message" id="id_message" /> <input type="text" name="message" id="id_message" />
For a field's list of errors, access the field's ``errors`` attribute. This 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:: is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
when printed::
>>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''} >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
>>> f = ContactForm(data, auto_id=False) >>> f = ContactForm(data, auto_id=False)
@ -673,7 +675,7 @@ Core field arguments
Each ``Field`` class constructor takes at least these arguments. Some Each ``Field`` class constructor takes at least these arguments. Some
``Field`` classes take additional, field-specific arguments, but the following ``Field`` classes take additional, field-specific arguments, but the following
should *always* be available: should *always* be accepted:
``required`` ``required``
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -731,7 +733,7 @@ field.)
The ``label`` argument lets you specify the "human-friendly" label for this The ``label`` argument lets you specify the "human-friendly" label for this
field. This is used when the ``Field`` is displayed in a ``Form``. 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 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 ``Field`` is generated from the field name by converting all underscores to
spaces and upper-casing the first letter. Specify ``label`` if that default spaces and upper-casing the first letter. Specify ``label`` if that default
behavior doesn't result in an adequate label. behavior doesn't result in an adequate label.
@ -806,14 +808,15 @@ validation if a particular field's value is not given. ``initial`` values are
~~~~~~~~~~ ~~~~~~~~~~
The ``widget`` argument lets you specify a ``Widget`` class to use when The ``widget`` argument lets you specify a ``Widget`` class to use when
rendering this ``Field``. See _`Widgets` below for more information. rendering this ``Field``. See "Widgets" below for more information.
``help_text`` ``help_text``
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The ``help_text`` argument lets you specify descriptive text for this 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``. If you provide ``help_text``, it will be displayed next to the
``Field`` when the ``Field`` is rendered in a ``Form``. ``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 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:: fields. We've specified ``auto_id=False`` to simplify the output::
@ -887,6 +890,212 @@ level and at the form instance level, and the latter gets precedence::
<tr><th>Url:</th><td><input type="text" name="url" /></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> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
Built-in ``Field`` classes
--------------------------
Naturally, the ``newforms`` library comes with a set of ``Field`` classes that
represent common validation needs. This section documents each built-in field.
For each field, we describe the default widget used if you don't specify
``widget``. We also specify the value returned when you provide an empty value
(see the section on ``required`` above to understand what that means).
``BooleanField``
~~~~~~~~~~~~~~~~
* Default widget: ``CheckboxInput``
* Empty value: ``None``
* Normalizes to: A Python ``True`` or ``False`` value.
* Validates nothing (i.e., it never raises a ``ValidationError``).
``CharField``
~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``''`` (an empty string)
* Normalizes to: A Unicode object.
* Validates nothing, unless ``max_length`` or ``min_length`` is provided.
Has two optional arguments for validation, ``max_length`` and ``min_length``.
If provided, these arguments ensure that the string is at most or at least the
given length.
``ChoiceField``
~~~~~~~~~~~~~~~
* Default widget: ``Select``
* Empty value: ``''`` (an empty string)
* Normalizes to: A Unicode object.
* Validates that the given value exists in the list of choices.
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field.
``DateField``
~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``None``
* Normalizes to: A Python ``datetime.date`` object.
* Validates that the given value is either a ``datetime.date``,
``datetime.datetime`` or string formatted in a particular date format.
Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.date`` object.
If no ``input_formats`` argument is provided, the default input formats are::
'%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
'%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006'
'%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006'
'%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006'
'%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006'
``DateTimeField``
~~~~~~~~~~~~~~~~~
* Default widget: ``TextInput``
* 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.
Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.datetime`` object.
If no ``input_formats`` argument is provided, the default input formats are::
'%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59'
'%Y-%m-%d %H:%M', # '2006-10-25 14:30'
'%Y-%m-%d', # '2006-10-25'
'%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59'
'%m/%d/%Y %H:%M', # '10/25/2006 14:30'
'%m/%d/%Y', # '10/25/2006'
'%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59'
'%m/%d/%y %H:%M', # '10/25/06 14:30'
'%m/%d/%y', # '10/25/06'
``EmailField``
~~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``''`` (an empty string)
* Normalizes to: A Unicode object.
* Validates that the given value is a valid e-mail address, using a
moderately complex regular expression.
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.
``IntegerField``
~~~~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``None``
* Normalizes to: A Python integer or long integer.
* Validates that the given value is an integer. Leading and trailing
whitespace is allowed, as in Python's ``int()`` function.
``MultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~
* Default widget: ``SelectMultiple``
* Empty value: ``[]`` (an empty list)
* Normalizes to: A list of Unicode objects.
* Validates that every value in the given list of values exists in the list
of choices.
Takes one extra argument, ``choices``, which is an iterable (e.g., a list or
tuple) of 2-tuples to use as choices for this field.
``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~
* Default widget: ``NullBooleanSelect``
* Empty value: ``None``
* Normalizes to: A Python ``True``, ``False`` or ``None`` value.
* Validates nothing (i.e., it never raises a ``ValidationError``).
``RegexField``
~~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``''`` (an empty string)
* Normalizes to: A Unicode object.
* Validates that the given value matches against a certain regular
expression.
Takes one required argument, ``regex``, which is a regular expression specified
either as a string or a compiled regular expression object.
Also takes the following optional arguments:
====================== =====================================================
Argument Description
====================== =====================================================
``max_length`` Ensures the string has at most this many characters.
``min_length`` Ensures the string has at least this many characters.
``error_message`` Error message to return for failed validation. If no
message is provided, a generic error message will be
used.
====================== =====================================================
``TimeField``
~~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``None``
* Normalizes to: A Python ``datetime.time`` object.
* Validates that the given value is either a ``datetime.time`` or string
formatted in a particular time format.
Takes one optional argument, ``input_formats``, which is a list of formats used
to attempt to convert a string to a valid ``datetime.time`` object.
If no ``input_formats`` argument is provided, the default input formats are::
'%H:%M:%S', # '14:30:59'
'%H:%M', # '14:30'
``URLField``
~~~~~~~~~~~~
* Default widget: ``TextInput``
* Empty value: ``''`` (an empty string)
* Normalizes to: A Unicode object.
* Validates that the given value is a valid URL.
Takes the following optional arguments:
======================== =====================================================
Argument Description
======================== =====================================================
``max_length`` Ensures the string has at most this many characters.
``min_length`` Ensures the string has at least this many characters.
``verify_exists`` If ``True``, the validator will attempt to load the
given URL, raising ``ValidationError`` if the page
gives a 404. Defaults to ``False``.
``validator_user_agent`` String used as the user-agent used when checking for
a URL's existence. Defaults to the value of the
``URL_VALIDATOR_USER_AGENT`` setting.
======================== =====================================================
Slightly complex built-in ``Field`` classes
-------------------------------------------
The following are not yet documented here. See the unit tests, linked-to from
the bottom of this document, for examples of their use.
``ComboField``
~~~~~~~~~~~~~~
``MultiValueField``
~~~~~~~~~~~~~~~~~~~
``SplitDateTimeField``
~~~~~~~~~~~~~~~~~~~~~~
Creating custom fields Creating custom fields
---------------------- ----------------------