diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 91aad0a798..c65c705a58 100644 --- a/docs/topics/forms/modelforms.txt +++ b/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::