newforms-admin: Merged from trunk up to [7120].

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7121 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 49 insertions, 4 deletions

diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 0136540bed..b9f0d88165 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -17,7 +17,7 @@ class from a Django model.
 For example::
 
     >>> from django.newforms import ModelForm
-    
+
     # Create the form class.
     >>> class ArticleForm(ModelForm):
     ...     class Meta:
@@ -113,7 +113,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`_ below.
 
 A full example
 --------------
@@ -278,7 +278,7 @@ model fields:
     To avoid this failure, you must instantiate your model with initial values
     for the missing, but required fields, or use ``save(commit=False)`` and
     manually set any extra required fields::
-    
+
         instance = Instance(required_field='value')
         form = InstanceForm(request.POST, instance=instance)
         new_instance = form.save()
@@ -295,7 +295,7 @@ model fields:
 Overriding the default field types
 ----------------------------------
 
-The default field types, as described in the "Field types" table above, are
+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
@@ -311,3 +311,48 @@ field, you could do the following::
     ...
     ...     class Meta:
     ...         model = Article
+
+If you want to override a field's default widget, then specify the ``widget``
+parameter when declaring the form field::
+
+   >>> class ArticleForm(ModelForm):
+   ...     pub_date = DateField(widget=MyDateWidget())
+   ...
+   ...     class Meta:
+   ...         model = Article
+
+Form inheritance
+----------------
+As with the basic forms, you can extend and reuse ``ModelForms`` by inheriting
+them. Normally, this will be useful if you need to declare some extra fields
+or extra methods on a parent class for use in a number of forms derived from
+models. For example, using the previous ``ArticleForm`` class::
+
+    >>> class EnhancedArticleForm(ArticleForm):
+    ...     def clean_pub_date(self):
+    ...         ...
+
+This creates a form that behaves identically to ``ArticleForm``, except there
+is some extra validation and cleaning for the ``pub_date`` field.
+
+You can also subclass the parent's ``Meta`` inner class if you want to change
+the ``Meta.fields`` or ``Meta.excludes`` lists::
+
+    >>> class RestrictedArticleForm(EnhancedArticleForm):
+    ...     class Meta(ArticleForm.Meta):
+    ...         exclude = ['body']
+
+This adds in the extra method from the ``EnhancedArticleForm`` and modifies
+the original ``ArticleForm.Meta`` to remove one field.
+
+There are a couple of things to note, however. Most of these won't normally be
+of concern unless you are trying to do something tricky with subclassing.
+
+ * Normal Python name resolution rules apply. If you have multiple base
+   classes that declare a ``Meta`` inner class, only the first one will be
+   used.  This means the child's ``Meta``, if it exists, otherwise the
+   ``Meta`` of the first parent, etc.
+
+ * For technical reasons, you cannot have a subclass that is inherited from
+   both a ``ModelForm`` and a ``Form`` simultaneously.
+