gis: Merged revisions 6525-6613 via svnmerge from [repos:django/trunk trunk].

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@6615 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 44 insertions, 8 deletions

diff --git a/docs/newforms.txt b/docs/newforms.txt
index 2005adeec8..5e33a478ee 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -100,7 +100,7 @@ Start with this basic ``Form`` subclass, which we'll call ``ContactForm``::
         subject = forms.CharField(max_length=100)
         message = forms.CharField()
         sender = forms.EmailField()
-        cc_myself = forms.BooleanField()
+        cc_myself = forms.BooleanField(required=False)
 
 A form is composed of ``Field`` objects. In this case, our form has four
 fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain
@@ -860,6 +860,23 @@ classes::
     <li>Instrument: <input type="text" name="instrument" /></li>
     <li>Haircut type: <input type="text" name="haircut_type" /></li>
 
+
+Prefixes for forms
+------------------
+
+You can put several Django forms inside one ``<form>`` tag. To give each
+``Form`` its own namespace you need to use the ``prefix`` keyword argument::
+
+    >>> mother = PersonForm(prefix="mother")
+    >>> father = PersonForm(prefix="father")
+    >>> print mother.as_ul()
+    <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
+    <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
+    >>> print father.as_ul()
+    <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
+    <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>
+
+
 Fields
 ======
 
@@ -1043,7 +1060,7 @@ fields. We've specified ``auto_id=False`` to simplify the output::
     ...     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()
+    ...     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>
@@ -1122,9 +1139,20 @@ For each field, we describe the default widget used if you don't specify
 ~~~~~~~~~~~~~~~~
 
     * Default widget: ``CheckboxInput``
-    * Empty value: ``None``
+    * Empty value: ``False``
     * Normalizes to: A Python ``True`` or ``False`` value.
-    * Validates nothing (i.e., it never raises a ``ValidationError``).
+    * Validates that the check box is checked (i.e. the value is ``True``) if
+      the field has ``required=True``.
+
+**New in Django development version:** The empty value for a ``CheckboxInput``
+(and hence the standard ``BooleanField``) has changed to return ``False``
+instead of ``None`` in the development version.
+
+.. note::
+    Since all ``Field`` subclasses have ``required=True`` by default, the
+    validation condition here is important. If you want to include a checkbox
+    in your form that can be either checked or unchecked, you must remember to
+    pass in ``required=False`` when creating the ``BooleanField``.
 
 ``CharField``
 ~~~~~~~~~~~~~
@@ -1132,7 +1160,8 @@ For each field, we describe the default widget used if you don't specify
     * Default widget: ``TextInput``
     * Empty value: ``''`` (an empty string)
     * Normalizes to: A Unicode object.
-    * Validates nothing, unless ``max_length`` or ``min_length`` is provided.
+    * Validates ``max_length`` or ``min_length``, if they are provided.
+      Otherwise, all inputs are valid.
 
 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
@@ -1172,7 +1201,7 @@ If no ``input_formats`` argument is provided, the default input formats are::
 ``DateTimeField``
 ~~~~~~~~~~~~~~~~~
 
-    * Default widget: ``TextInput``
+    * Default widget: ``DateTimeInput``
     * Empty value: ``None``
     * Normalizes to: A Python ``datetime.datetime`` object.
     * Validates that the given value is either a ``datetime.datetime``,
@@ -1193,6 +1222,9 @@ If no ``input_formats`` argument is provided, the default input formats are::
     '%m/%d/%y %H:%M',        # '10/25/06 14:30'
     '%m/%d/%y',              # '10/25/06'
 
+**New in Django development version:** The ``DateTimeField`` used to use a
+``TextInput`` widget by default. This has now changed.
+
 ``DecimalField``
 ~~~~~~~~~~~~~~~~
 
@@ -1508,7 +1540,7 @@ like so::
         subject = forms.CharField(max_length=100)
         message = forms.CharField()
         senders = MultiEmailField()
-        cc_myself = forms.BooleanField()
+        cc_myself = forms.BooleanField(required=False)
 
 Widgets
 =======
@@ -1529,6 +1561,7 @@ commonly used groups of widgets:
     ``MultipleHiddenInput``       Multiple ``<input type='hidden' ...``
                                   instances.
     ``FileInput``                 ``<input type='file' ...``
+    ``DateTimeInput``             ``<input type='text' ...``
     ``Textarea``                  ``<textarea>...</textarea>``
     ``CheckboxInput``             ``<input type='checkbox' ...``
     ``Select``                    ``<select><option ...``
@@ -1542,6 +1575,9 @@ commonly used groups of widgets:
                                   one for the Date, and one for the Time.
     ============================  ===========================================
 
+**New in Django development version:** The ``DateTimeInput`` has been added
+since the last release.
+
 Specifying widgets
 ------------------
 
@@ -2033,7 +2069,7 @@ have a ``Message`` model that holds each contact submission. Something like::
         subject = models.CharField(max_length=100)
         message = models.TextField()
         sender = models.EmailField()
-        cc_myself = models.BooleanField()
+        cc_myself = models.BooleanField(required=False)
 
 You could use this model to create a form (using ``form_for_model()``). You
 could also use existing ``Message`` instances to create a form for editing