Kaydet (Commit) 54cd930b authored tarafından Loic Bistuer's avatar Loic Bistuer Kaydeden (comit) Tim Graham

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.
üst 9b7d38ed
......@@ -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::
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment