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
parent
0810919694
commit
70703a6b71
|
|
@ -481,7 +481,7 @@ field::
|
|||
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_%s'``, a field named ``subject`` will get the ``id`` value
|
||||
``'field_subject'``. Continuing our example::
|
||||
|
||||
>>> 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
|
||||
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::
|
||||
will include the validation errors as a ``<ul class="errorlist">`` near the
|
||||
field. The particular positioning of the error messages depends on the output
|
||||
method you're using::
|
||||
|
||||
>>> data = {'subject': '',
|
||||
... '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" />
|
||||
|
||||
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': ''}
|
||||
>>> f = ContactForm(data, auto_id=False)
|
||||
|
|
@ -673,7 +675,7 @@ 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:
|
||||
should *always* be accepted:
|
||||
|
||||
``required``
|
||||
~~~~~~~~~~~~
|
||||
|
|
@ -731,7 +733,7 @@ field.)
|
|||
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
|
||||
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.
|
||||
|
|
@ -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
|
||||
rendering this ``Field``. See _`Widgets` below for more information.
|
||||
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``.
|
||||
``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::
|
||||
|
|
@ -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>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
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue