Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.6.x] Clarfied the ModelForm docs with respect to generated vs. dec…

…lared 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 54cd930 from master
  • Loading branch information...
commit 8222a48253e61f4d3c1d30156a5f9e0d59a7c56c 1 parent da18105
@loic loic authored timgraham committed
Showing with 22 additions and 11 deletions.
  1. +22 −11 docs/topics/forms/modelforms.txt
View
33 docs/topics/forms/modelforms.txt
@@ -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::
Please sign in to comment.
Something went wrong with that request. Please try again.