Commit 8222a482 authored by Loic Bistuer's avatar Loic Bistuer Committed by Tim Graham
Browse files

[1.6.x] Clarfied the ModelForm docs with respect to generated vs. declared fields. 

The ModelForm docs suggested that fields defined declaratively override
default fields generated from the form Meta.

This is conceptually wrong, especially with inheritance in mind. Meta is
usually defined on the topmost ModelForm subclass, while fields can come
from anywhere in the MRO, especially base classes; therefore we suggested
that something defined in a base class override something from a subclass.

This patch rephrases the docs around the idea that Meta is used to generate
*missing* fields.

Refs #8620, #19617.

Thanks @mjtamlyn and @timgraham for the review.

Backport of 54cd930b from master
parent da181056

docs/topics/forms/modelforms.txt

+22 −11
Original line number Diff line number Diff line
@@ -515,10 +515,7 @@ the ``name`` field:: 


Finally, if you want complete control over of a field -- including its type,

validators, etc. -- you can do this by declaratively specifying fields like you

would in a regular ``Form``. Declared fields will override the default ones

generated by using the ``model`` attribute. Fields declared like this will

ignore any customizations in the ``widgets``, ``labels``, ``help_texts``, and

``error_messages`` options declared on ``Meta``.

would in a regular ``Form``.



For example, if you wanted to use ``MySlugFormField`` for the ``slug``

field, you could do the following::
@@ -534,8 +531,8 @@ field, you could do the following:: 
            fields = ['pub_date', 'headline', 'content', 'reporter']





If you want to override a field's default validators, then specify the

``validators`` parameter when declaring the form field::

If you want to specify a field's validators, you can do so by defining

the field declaratively and setting its ``validators`` parameter::



    from django.forms import ModelForm, DateField

    from myapp.models import Article
@@ -549,11 +546,25 @@ If you want to override a field's default validators, then specify the 


.. note::



    If you explicitly instantiate a form field like this, Django assumes that you

    want to completely define its behavior; therefore, default attributes (such as

    ``max_length`` or ``required``) are not drawn from the corresponding model. If

    you want to maintain the behavior specified in the model, you must set the

    relevant arguments explicitly when declaring the form field.

    When you explicitly instantiate a form field like this, it is important to

    understand how ``ModelForm`` and regular ``Form`` are related.



    ``ModelForm`` is a regular ``Form`` which can automatically generate

    certain fields. The fields that are automatically generated depend on

    the content of the ``Meta`` class and on which fields have already been

    defined declaratively. Basically, ``ModelForm`` will **only** generate fields

    that are **missing** from the form, or in other words, fields that weren't

    defined declaratively.



    Fields defined declaratively are left as-is, therefore any customizations

    made to ``Meta`` attributes such as ``widgets``, ``labels``, ``help_texts``,

    or ``error_messages`` are ignored; these only apply to fields that are

    generated automatically.



    Similarly, fields defined declaratively do not draw their attributes like

    ``max_length`` or ``required`` from the corresponding model. If you want to

    maintain the behavior specified in the model, you must set the relevant

    arguments explicitly when declaring the form field.



    For example, if the ``Article`` model looks like this::