From 70703a6b71a4263594c450c9f24052deb1eefc08 Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Mon, 14 May 2007 05:32:35 +0000
Subject: [PATCH] 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
---
 docs/newforms.txt | 225 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 217 insertions(+), 8 deletions(-)

diff --git a/docs/newforms.txt b/docs/newforms.txt
index 58571bd02e..7c861ed405 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -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
 ----------------------