Merge pull request #210 from pydanny/ticket_18632

Ticket 18632 Cleanup of CBV edit/edit mixin documentation.

2 files changed, 126 insertions, 4 deletions

diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt
index d5df369fb3..a65a59bc8b 100644
--- a/docs/ref/class-based-views/generic-editing.txt
+++ b/docs/ref/class-based-views/generic-editing.txt
@@ -2,7 +2,28 @@
 Generic editing views
 =====================
 
-The views described here provide a foundation for editing content.
+The following views are described on this page and provide a foundation for 
+editing content:
+
+* :class:`django.views.generic.edit.FormView`
+* :class:`django.views.generic.edit.CreateView`
+* :class:`django.views.generic.edit.UpdateView`
+* :class:`django.views.generic.edit.DeleteView`
+
+.. note::
+
+    Some of the examples on this page assume that a model titled 'Author'
+    has been defined. For these cases we assume the following has been defined 
+    in `myapp/models.py`::
+
+        from django import models
+        from django.core.urlresolvers import reverse
+
+        class Author(models.Model):
+            name = models.CharField(max_length=200)
+
+            def get_absolute_url(self):
+                return reverse('author-detail', kwargs={'pk': self.pk})
 
 .. class:: django.views.generic.edit.FormView
 
@@ -11,6 +32,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.FormView`
     * :class:`django.views.generic.base.TemplateResponseMixin`
     * :class:`django.views.generic.edit.BaseFormView`
@@ -18,6 +41,35 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Example forms.py**::
+
+        from django import forms
+
+        class ContactForm(forms.Form):
+            name = forms.CharField()
+            message = forms.CharField(widget=forms.Textarea)
+
+            def send_email(self):
+                # send email using the self.cleaned_data dictionary
+                pass
+
+    **Example views.py**::
+
+        from myapp.forms import ContactForm
+        from django.views.generic.edit import FormView
+
+        class ContactView(FormView):
+            template_name = 'contact.html'
+            form_class = ContactForm
+            success_url = '/thanks/'
+
+            def form_valid(self, form):
+                # This method is called when valid form data has been POSTed.
+                # It should return an HttpResponse.
+                form.send_email()
+                return super(ContactView, self).form_valid(form)
+
+
 .. class:: django.views.generic.edit.CreateView
 
     A view that displays a form for creating an object, redisplaying the form
@@ -25,6 +77,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.CreateView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -35,6 +89,24 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The CreateView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_form.html'``. For 
+        example, changing this attribute to ``'_create_form.html'`` for a view
+        creating objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_create_form.html'``.
+
+    **Example views.py**::
+
+        from django.views.generic.edit import CreateView
+        from myapp.models import Author
+
+        class AuthorCreate(CreateView):
+            model = Author
+
 .. class:: django.views.generic.edit.UpdateView
 
     A view that displays a form for editing an existing object, redisplaying
@@ -44,6 +116,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.UpdateView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -54,6 +128,24 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The UpdateView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_form.html'``. For 
+        example, changing this attribute to ``'_update_form.html'`` for a view
+        updating objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_update_form.html'``.        
+
+    **Example views.py**::
+
+        from django.views.generic.edit import UpdateView
+        from myapp.models import Author
+
+        class AuthorUpdate(UpdateView):
+            model = Author
+
 .. class:: django.views.generic.edit.DeleteView
 
     A view that displays a confirmation page and deletes an existing object.
@@ -63,6 +155,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.DeleteView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -72,7 +166,23 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.detail.SingleObjectMixin`
     * :class:`django.views.generic.base.View`
 
-    **Notes**
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The DeleteView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_confirm_delete.html'``. For 
+        example, changing this attribute to ``'_check_delete.html'`` for a view
+        deleting objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_check_delete.html'``.        
+
+
+    **Example views.py**::
+
+        from django.views.generic.edit import DeleteView
+        from django.core.urlresolvers import reverse_lazy
+        from myapp.models import Author
 
-    * The delete confirmation page displayed to a GET request uses a
-      ``template_name_suffix`` of ``'_confirm_delete'``.
+        class AuthorDelete(DeleteView):
+            model = Author
+            success_url = reverse_lazy('author-list')        
diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt
index 7258893d63..89610889db 100644
--- a/docs/ref/class-based-views/mixins-editing.txt
+++ b/docs/ref/class-based-views/mixins-editing.txt
@@ -2,6 +2,18 @@
 Editing mixins
 ==============
 
+The following mixins are used to construct Django's editing views:
+
+* :class:`django.views.generic.edit.FormMixin`
+* :class:`django.views.generic.edit.ModelFormMixin`
+* :class:`django.views.generic.edit.ProcessFormView`
+* :class:`django.views.generic.edit.DeletionMixin`
+
+.. note::
+
+    Examples of how these are combined into editing views can be found at
+    the documentation on ``Generic editing views``.
+
 .. class:: django.views.generic.edit.FormMixin
 
     A mixin class that provides facilities for creating and displaying forms.