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.
This commit is contained in:
parent
9b7d38ed5a
commit
54cd930baf
|
@ -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::
|
||||
|
||||
|
|
Loading…
Reference in New Issue