Fixed 11674 -- Clarified docs on excluded fields of ModelForms.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16875 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 17 insertions, 7 deletions

diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index 07c7b02c19..07a2819fa3 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -331,13 +331,17 @@ Since the Author model has only 3 fields, 'name', 'title', and
 .. note::
 
     If you specify ``fields`` or ``exclude`` when creating a form with
-    ``ModelForm``, then the fields that are not in the resulting form will not
-    be set by the form's ``save()`` method. Django will prevent any attempt to
-    save an incomplete model, so if the model does not allow the missing fields
-    to be empty, and does not provide a default value for the missing fields,
-    any attempt to ``save()`` a ``ModelForm`` with missing fields will fail.
-    To avoid this failure, you must instantiate your model with initial values
-    for the missing, but required fields::
+    ``ModelForm``, then the fields that are not in the resulting form
+    will not be set by the form's ``save()`` method. Also, if you
+    manually add the excluded fields back to the form, they will not
+    be initialized from the model instance.
+
+    Django will prevent any attempt to save an incomplete model, so if
+    the model does not allow the missing fields to be empty, and does
+    not provide a default value for the missing fields, any attempt to
+    ``save()`` a ``ModelForm`` with missing fields will fail.  To
+    avoid this failure, you must instantiate your model with initial
+    values for the missing, but required fields::
 
         author = Author(title='Mr')
         form = PartialAuthorForm(request.POST, instance=author)
@@ -632,6 +636,12 @@ database. If a given instance's data didn't change in the bound data, the
 instance won't be saved to the database and won't be included in the return
 value (``instances``, in the above example).
 
+When fields are missing from the form (for example because they have
+been excluded), these fields will not be set by the ``save()``
+method. You can find more information about this restriction, which
+also holds for regular ``ModelForms``, in `Using a subset of fields on
+the form`_.
+
 Pass ``commit=False`` to return the unsaved model instances::
 
     # don't save to the database