From 9bb1fa725154e6d1d0317fa0c48d7c240ad5e2d4 Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Sun, 10 Jan 2010 19:23:42 +0000
Subject: Fixed #9223 -- Added support for declarative widgets to ModelForm. I
 declare thanks to isagalaev.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12194 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/topics/forms/modelforms.txt | 50 +++++++++++++++++++++++++++++-----------
 1 file changed, 36 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index 7049464f86..e1a90262d9 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -146,7 +146,7 @@ In addition, each generated form field has attributes set as follows:
       ``default`` value will be initially selected instead).
 
 Finally, note that you can override the form field used for a given model
-field. See `Overriding the default field types`_ below.
+field. See `Overriding the default field types or widgets`_ below.
 
 A full example
 --------------
@@ -350,31 +350,53 @@ Since the Author model has only 3 fields, 'name', 'title', and
 
 .. _section on saving forms: `The save() method`_
 
-Overriding the default field types
-----------------------------------
+Overriding the default field types or widgets
+---------------------------------------------
 
 The default field types, as described in the `Field types`_ table above, are
 sensible defaults. If you have a ``DateField`` in your model, chances are you'd
 want that to be represented as a ``DateField`` in your form. But
-``ModelForm`` gives you the flexibility of changing the form field type
-for a given model field. You 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.
+``ModelForm`` gives you the flexibility of changing the form field type and 
+widget for a given model field.
+
+To specify a custom widget for a field, use the ``widgets`` attribute of the
+inner ``Meta`` class. This should be a dictionary mapping field names to widget
+classes or instances.
+
+For example, if you want the a ``CharField`` to be represented by a
+``<textarea>`` instead of its default ``<input type="text">``, you can override
+the field's widget::
+
+    class AuthorForm(ModelForm):
+        class Meta:
+            model = Author
+            fields = ['name', 'title', 'birth_date']
+            widgets = {
+                'name': Textarea(attrs={'cols': 80, 'rows': 20}),
+            }
+
+The ``widgets`` dictionary accepts either widget instances (e.g.,
+``Textarea(...)``) or classes (e.g., ``Textarea``).
+
+If you want to further customize a field -- including its type, label, 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.
 
 For example, if you wanted to use ``MyDateFormField`` for the ``pub_date``
 field, you could do the following::
 
-    >>> class ArticleForm(ModelForm):
-    ...     pub_date = MyDateFormField()
-    ...
-    ...     class Meta:
-    ...         model = Article
+    class ArticleForm(ModelForm):
+        pub_date = MyDateFormField()
+    
+        class Meta:
+            model = Article
 
-If you want to override a field's default widget, then specify the ``widget``
+If you want to override a field's default label, then specify the ``label``
 parameter when declaring the form field::
 
    >>> class ArticleForm(ModelForm):
-   ...     pub_date = DateField(widget=MyDateWidget())
+   ...     pub_date = DateField(label='Publication date')
    ...
    ...     class Meta:
    ...         model = Article
-- 
cgit v1.3