Commit 4f109fcb authored by Paul McMillan's avatar Paul McMillan
Browse files

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
parent 4f9cf2ef
Loading
Loading
Loading
Loading
+17 −7
Original line number Diff line number Diff line
@@ -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