Ticket #3780: newforms_field_list.2.patch

docs/newforms.txt

@@ -859 +859 @@
     <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
+Field types
+-----------
+
+``BooleanField``
+~~~~~~~~~~~~~~~~
+
+Default widget: ``CheckboxInput``
+
+Cleans to a Python ``True`` or ``False`` value.
+
+``CharField``
+~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Has two optional arguments for validation, ``max_length`` and ``min_length``
+which if provided, ensure that the string is at most or at least the given
+length.
+
+``ChoiceField``
+~~~~~~~~~~~~~~~
+
+Default widget: ``Select``
+
+Cleans to a one of the values given in ``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.
+
+``ComboField``
+~~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Takes one extra argument, ``fields``, which is a list of fields which are used
+(in order) to clean the provided value.
+
+``DateField``
+~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Cleans to a ``datetime.date`` object. Accepts ``datetime.datetime``, 
+``datetime.date`` and strings.
+
+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``
+
+Cleans to a ``datetime.datetime`` object. Accepts ``datetime.datetime``, 
+``datetime.date`` and strings.
+
+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``
+
+Based on a ``RegexField``, checks that the provided string looks like a
+valid email when cleaning.
+
+Has two optional arguments for validation, ``max_length`` and ``min_length``
+which if provided, ensure that the string is at most or at least the given
+length.
+
+``Field``
+~~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+This is the base ``Field`` type usually not used directly.
+
+``IntegerField``
+~~~~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Cleans to an Python ``int`` (or ``long``) object.
+
+``MultiValueField``
+~~~~~~~~~~~~~~~~~~~
+
+Composed of multiple ``Field``s, this is a base ``Field`` type not used
+directly.
+
+Its ``clean()`` method takes a "decompressed" list of values. Each value in
+this list is cleaned by the corresponding field -- 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 using a ``compress()`` method defined
+in sub-classes.
+
+You'll probably want to use this with ``MultiWidget``.
+
+``MultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Default widget: ``SelectMultiple``
+
+Cleans to a list of values given in ``choices`` (Takes a python ``list`` or
+``tuple``).
+
+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``
+
+Cleans to a Python ``True``, ``False`` or ``None`` value. Invalid values are
+cleaned to ``None``.
+
+``NullBooleanField``
+~~~~~~~~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Validates a string using a regular expression.
+
+Takes the following arguments, used during cleaning:
+
+    ======================  ===================================================
+    Argument                Description
+    ======================  ===================================================
+    ``regex``               Either a string or a compiled regular expression
+                            object used for validation. Required argument. 
+    ``max_length``          Optional value to ensure the string has at most
+                            this many characters.
+    ``min_length``          Optional value to ensure the string has at least
+                            this many characters.
+    ``error_message``       Optional error message to return for failed
+                            validation. If no message is provided, a generic
+                            error message will be used.
+    ======================  ===================================================
+
+``SplitDateTimeField``
+~~~~~~~~~~~~~~~~~~~~~~
+
+A ``MultiValueField`` which combines a ``DateField`` and a ``TimeField`` to a
+single ``datetime.datetime`` object.
+
+``TimeField``
+~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Cleans to a ``datetime.time`` object. Accepts ``datetime.time`` and string
+objects.
+
+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::
+
+    '%H:%M:%S',     # '14:30:59'
+    '%H:%M',        # '14:30'
+
+``URLField``
+~~~~~~~~~~~~~~
+
+Default widget: ``TextInput``
+
+Based on a ``RegexField``, checks that the provided string is a valid URL
+when cleaning.
+
+Takes the following arguments:
+
+    ========================  =================================================
+    Argument                  Description
+    ========================  =================================================
+    ``max_length``            Optional value to ensure the string has at most
+                              this many characters.
+    ``min_length``            Optional value to ensure the string has at least
+                              this many characters.
+    ``verify_exists``         If ``True``, the URL given will be checked for
+                              existence (i.e., the URL actually loads and
+                              doesn't give a 404 response). Defaults to
+                              ``False``.
+    ``validator_user_agent``  Optional string used as the user-agent used when
+                              checking for a URL's existence. Defaults to
+                              ``settings.URL_VALIDATOR_USER_AGENT`` or if not
+                              found there,
+                              ``'Django (http://www.djangoproject.com/)'``.
+    ========================  =================================================
+
 More coming soon
 ================