Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[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 Bistuer authored timgraham committed

Showing 1 changed file with 22 additions and 11 deletions. Show diff stats Hide diff stats

  1. 33  docs/topics/forms/modelforms.txt
33  docs/topics/forms/modelforms.txt
@@ -515,10 +515,7 @@ the ``name`` field::
515 515
 
516 516
 Finally, if you want complete control over of a field -- including its type,
517 517
 validators, etc. -- you can do this by declaratively specifying fields like you
518  
-would in a regular ``Form``. Declared fields will override the default ones
519  
-generated by using the ``model`` attribute. Fields declared like this will
520  
-ignore any customizations in the ``widgets``, ``labels``, ``help_texts``, and
521  
-``error_messages`` options declared on ``Meta``.
  518
+would in a regular ``Form``.
522 519
 
523 520
 For example, if you wanted to use ``MySlugFormField`` for the ``slug``
524 521
 field, you could do the following::
@@ -534,8 +531,8 @@ field, you could do the following::
534 531
             fields = ['pub_date', 'headline', 'content', 'reporter']
535 532
 
536 533
 
537  
-If you want to override a field's default validators, then specify the
538  
-``validators`` parameter when declaring the form field::
  534
+If you want to specify a field's validators, you can do so by defining
  535
+the field declaratively and setting its ``validators`` parameter::
539 536
 
540 537
     from django.forms import ModelForm, DateField
541 538
     from myapp.models import Article
@@ -549,11 +546,25 @@ If you want to override a field's default validators, then specify the
549 546
 
550 547
 .. note::
551 548
 
552  
-    If you explicitly instantiate a form field like this, Django assumes that you
553  
-    want to completely define its behavior; therefore, default attributes (such as
554  
-    ``max_length`` or ``required``) are not drawn from the corresponding model. If
555  
-    you want to maintain the behavior specified in the model, you must set the
556  
-    relevant arguments explicitly when declaring the form field.
  549
+    When you explicitly instantiate a form field like this, it is important to
  550
+    understand how ``ModelForm`` and regular ``Form`` are related.
  551
+
  552
+    ``ModelForm`` is a regular ``Form`` which can automatically generate
  553
+    certain fields. The fields that are automatically generated depend on
  554
+    the content of the ``Meta`` class and on which fields have already been
  555
+    defined declaratively. Basically, ``ModelForm`` will **only** generate fields
  556
+    that are **missing** from the form, or in other words, fields that weren't
  557
+    defined declaratively.
  558
+
  559
+    Fields defined declaratively are left as-is, therefore any customizations
  560
+    made to ``Meta`` attributes such as ``widgets``, ``labels``, ``help_texts``,
  561
+    or ``error_messages`` are ignored; these only apply to fields that are
  562
+    generated automatically.
  563
+
  564
+    Similarly, fields defined declaratively do not draw their attributes like
  565
+    ``max_length`` or ``required`` from the corresponding model. If you want to
  566
+    maintain the behavior specified in the model, you must set the relevant
  567
+    arguments explicitly when declaring the form field.
557 568
 
558 569
     For example, if the ``Article`` model looks like this::
559 570
 

0 notes on commit 8222a48

Please sign in to comment.
Something went wrong with that request. Please try again.