Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #10336 -- Added improved documentation of generic views. Thanks…

… to Jacob and Adrian for the original text (from the DjangoBook), and Ramiro for doing the work of porting the docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11025 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 6c81952b379712a5bbd4e4d73ec88a07d875b68e 1 parent 992ded1
Russell Keith-Magee authored June 17, 2009
11  docs/index.txt
@@ -98,10 +98,13 @@ The view layer
98 98
       :ref:`Storage API <ref-files-storage>` | 
99 99
       :ref:`Managing files <topics-files>` | 
100 100
       :ref:`Custom storage <howto-custom-file-storage>`
101  
-          
102  
-    * **Advanced:** 
103  
-      :ref:`Generic views <ref-generic-views>` | 
104  
-      :ref:`Generating CSV <howto-outputting-csv>` | 
  101
+
  102
+    * **Generic views:**
  103
+      :ref:`Overview<topics-generic-views>` |
  104
+      :ref:`Built-in generic views<ref-generic-views>`
  105
+
  106
+    * **Advanced:**
  107
+      :ref:`Generating CSV <howto-outputting-csv>` |
105 108
       :ref:`Generating PDF <howto-outputting-pdf>`
106 109
     
107 110
     * **Middleware:** 
5  docs/internals/documentation.txt
@@ -130,11 +130,6 @@ TODO
130 130
 
131 131
 The work is mostly done, but here's what's left, in rough order of priority.
132 132
 
133  
-    * Fix up generic view docs: adapt Chapter 9 of the Django Book (consider
134  
-      this TODO item my permission and license) into
135  
-      ``topics/generic-views.txt``; remove the intro material from
136  
-      ``ref/generic-views.txt`` and just leave the function reference.
137  
-
138 133
     * Change the "Added/changed in development version" callouts to proper
139 134
       Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
140 135
 
71  docs/ref/generic-views.txt
@@ -9,67 +9,18 @@ again and again. In Django, the most common of these patterns have been
9 9
 abstracted into "generic views" that let you quickly provide common views of
10 10
 an object without actually needing to write any Python code.
11 11
 
12  
-Django's generic views contain the following:
  12
+A general introduction to generic views can be found in the :ref:`topic guide
  13
+<topics-generic-views>`.
13 14
 
14  
-    * A set of views for doing list/detail interfaces.
15  
-
16  
-    * A set of views for year/month/day archive pages and associated
17  
-      detail and "latest" pages (for example, the Django weblog's year_,
18  
-      month_, day_, detail_, and latest_ pages).
19  
-
20  
-    * A set of views for creating, editing, and deleting objects.
21  
-
22  
-.. _year: http://www.djangoproject.com/weblog/2005/
23  
-.. _month: http://www.djangoproject.com/weblog/2005/jul/
24  
-.. _day: http://www.djangoproject.com/weblog/2005/jul/20/
25  
-.. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/
26  
-.. _latest: http://www.djangoproject.com/weblog/
27  
-
28  
-All of these views are used by creating configuration dictionaries in
29  
-your URLconf files and passing those dictionaries as the third member of the
30  
-URLconf tuple for a given pattern. For example, here's the URLconf for the
31  
-simple weblog app that drives the blog on djangoproject.com::
32  
-
33  
-    from django.conf.urls.defaults import *
34  
-    from django_website.apps.blog.models import Entry
35  
-
36  
-    info_dict = {
37  
-        'queryset': Entry.objects.all(),
38  
-        'date_field': 'pub_date',
39  
-    }
40  
-
41  
-    urlpatterns = patterns('django.views.generic.date_based',
42  
-       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', info_dict),
43  
-       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$',               'archive_day',   info_dict),
44  
-       (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$',                                'archive_month', info_dict),
45  
-       (r'^(?P<year>\d{4})/$',                                                    'archive_year',  info_dict),
46  
-       (r'^$',                                                                    'archive_index', info_dict),
47  
-    )
48  
-
49  
-As you can see, this URLconf defines a few options in ``info_dict``.
50  
-``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this
51  
-case, all of the ``Entry`` objects) and tells the generic view which model is
52  
-being used.
53  
-
54  
-Documentation of each generic view follows, along with a list of all keyword
55  
-arguments that a generic view expects. Remember that as in the example above,
56  
-arguments may either come from the URL pattern (as ``month``, ``day``,
57  
-``year``, etc. do above) or from the additional-information dictionary (as for
58  
-``queryset``, ``date_field``, etc.).
  15
+This reference contains details of Django's built-in generic views, along with
  16
+a list of all keyword arguments that a generic view expects. Remember that
  17
+arguments may either come from the URL pattern or from the ``extra_context``
  18
+additional-information dictionary.
59 19
 
60 20
 Most generic views require the ``queryset`` key, which is a ``QuerySet``
61 21
 instance; see :ref:`topics-db-queries` for more information about ``QuerySet``
62 22
 objects.
63 23
 
64  
-Most views also take an optional ``extra_context`` dictionary that you can use
65  
-to pass any auxiliary information you wish to the view. The values in the
66  
-``extra_context`` dictionary can be either functions (or other callables) or
67  
-other objects. Functions are evaluated just before they are passed to the
68  
-template. However, note that QuerySets retrieve and cache their data when they
69  
-are first evaluated, so if you want to pass in a QuerySet via
70  
-``extra_context`` that is always fresh you need to wrap it in a function or
71  
-lambda that returns the QuerySet.
72  
-
73 24
 "Simple" generic views
74 25
 ======================
75 26
 
@@ -801,12 +752,12 @@ specify the page number in the URL in one of two ways:
801 752
 
802 753
         /objects/?page=3
803 754
 
804  
-    * To loop over all the available page numbers, use the ``page_range`` 
805  
-      variable. You can iterate over the list provided by ``page_range`` 
  755
+    * To loop over all the available page numbers, use the ``page_range``
  756
+      variable. You can iterate over the list provided by ``page_range``
806 757
       to create a link to every page of results.
807 758
 
808 759
 These values and lists are 1-based, not 0-based, so the first page would be
809  
-represented as page ``1``. 
  760
+represented as page ``1``.
810 761
 
811 762
 For more on pagination, read the :ref:`pagination documentation
812 763
 <topics-pagination>`.
@@ -818,7 +769,7 @@ As a special case, you are also permitted to use ``last`` as a value for
818 769
 
819 770
     /objects/?page=last
820 771
 
821  
-This allows you to access the final page of results without first having to 
  772
+This allows you to access the final page of results without first having to
822 773
 determine how many pages there are.
823 774
 
824 775
 Note that ``page`` *must* be either a valid page number or the value ``last``;
@@ -909,7 +860,7 @@ library <topics-forms-index>` to build and display the form.
909 860
 **Description:**
910 861
 
911 862
 A page that displays a form for creating an object, redisplaying the form with
912  
-validation errors (if there are any) and saving the object. 
  863
+validation errors (if there are any) and saving the object.
913 864
 
914 865
 **Required arguments:**
915 866
 
1  docs/topics/index.txt
@@ -14,6 +14,7 @@ Introductions to all the key parts of Django you'll need to know:
14 14
    forms/index
15 15
    forms/modelforms
16 16
    templates
  17
+   generic-views
17 18
    files
18 19
    testing
19 20
    auth

0 notes on commit 6c81952

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