mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-23 01:25:58 +00:00
Code Issues 25 Releases Wiki Activity

Clarfied the ModelForm docs with respect to generated vs. declared fields.

Browse Source 
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:
Loic Bistuer 2013-10-14 20:45:30 +07:00 committed by Tim Graham
parent 9b7d38ed5a
commit 54cd930baf
1 changed files with 22 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/topics/forms/modelforms.txt
View File

@ -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::