From 38055222bd4f56bac6ae0f7a53c07bf924967daf Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 27 Nov 2012 19:26:37 -0500 Subject: [PATCH] Fixed #19239 - Added examples for generic date views Thank-you Daniel Greenfeld and Scott Nixon. --- .../class-based-views/generic-date-based.txt | 299 +++++++++++++++++- .../ref/class-based-views/generic-editing.txt | 5 +- 2 files changed, 299 insertions(+), 5 deletions(-) diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt index c6af23e421..0ae0bcdf42 100644 --- a/docs/ref/class-based-views/generic-date-based.txt +++ b/docs/ref/class-based-views/generic-date-based.txt @@ -7,6 +7,21 @@ Generic date views Date-based generic views, provided in :mod:`django.views.generic.dates`, are views for displaying drilldown pages for date-based data. +.. note:: + + Some of the examples on this page assume that an ``Article`` model has been + defined as follows in ``myapp/models.py``:: + + from django.db import models + from django.core.urlresolvers import reverse + + class Article(models.Model): + title = models.CharField(max_length=200) + pub_date = models.DateField() + + def get_absolute_url(self): + return reverse('article-detail', kwargs={'pk': self.pk}) + ArchiveIndexView ---------------- @@ -35,6 +50,31 @@ ArchiveIndexView month or day using the attribute ``date_list_period``. This also applies to all subclass views. + **Example views.py**:: + + from django.conf.urls import patterns, url + from django.views.generic.dates import ArchiveIndexView + + from myapp.models import Article + + urlpatterns = patterns('', + url(r'^archive/$', + ArchiveIndexView.as_view(model=Article, date_field="pub_date"), + name="article_archive"), + ) + + **Example myapp/article_archive.html**: + + .. code-block:: html+django + + + + This will output all articles. + YearArchiveView --------------- @@ -109,6 +149,49 @@ YearArchiveView * Uses a default ``template_name_suffix`` of ``_archive_year``. + **Example views.py**:: + + from django.views.generic.dates import YearArchiveView + + from myapp.models import Article + + class ArticleYearArchiveView(YearArchiveView): + queryset = Article.objects.all() + date_field = "pub_date" + make_object_list = True + allow_future = True + + **Example urls.py**:: + + from django.conf.urls import patterns, url + + from myapp.views import ArticleYearArchiveView + + urlpatterns = patterns('', + url(r'^(?P\d{4})/$', + ArticleYearArchiveView.as_view(), + name="article_year_archive"), + ) + + **Example myapp/article_archive_year.html**: + + .. code-block:: html+django + + + +
+

All Articles for {{ year|date:"Y" }}

+ {% for obj in object_list %} +

+ {{ obj.title }} - {{ obj.pub_date|date:"F j, Y" }} +

+ {% endfor %} +
+ MonthArchiveView ---------------- @@ -162,6 +245,54 @@ MonthArchiveView * Uses a default ``template_name_suffix`` of ``_archive_month``. + **Example views.py**:: + + from django.views.generic.dates import MonthArchiveView + + from myapp.models import Article + + class ArticleMonthArchiveView(MonthArchiveView): + queryset = Article.objects.all() + date_field = "pub_date" + make_object_list = True + allow_future = True + + **Example urls.py**:: + + from django.conf.urls import patterns, url + + from myapp.views import ArticleMonthArchiveView + + urlpatterns = patterns('', + # Example: /2012/aug/ + url(r'^(?P\d{4})/(?P[-\w]+)/$', + ArticleMonthArchiveView.as_view(), + name="archive_month"), + # Example: /2012/08/ + url(r'^(?P\d{4})/(?P\d+)/$', + ArticleMonthArchiveView.as_view(month_format='%m'), + name="archive_month_numeric"), + ) + + **Example myapp/article_archive_month.html**: + + .. code-block:: html+django + +
    + {% for article in object_list %} +
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • + {% endfor %} +
+ +

+ {% if previous_month %} + Previous Month: {{ previous_month|date:"F Y" }} + {% endif %} + {% if next_month %} + Next Month: {{ next_month|date:"F Y" }} + {% endif %} +

+ WeekArchiveView --------------- @@ -208,6 +339,65 @@ WeekArchiveView * Uses a default ``template_name_suffix`` of ``_archive_week``. + **Example views.py**:: + + from django.views.generic.dates import WeekArchiveView + + from myapp.models import Article + + class ArticleWeekArchiveView(WeekArchiveView): + queryset = Article.objects.all() + date_field = "pub_date" + make_object_list = True + week_format = "%W" + allow_future = True + + **Example urls.py**:: + + from django.conf.urls import patterns, url + + from myapp.views import ArticleWeekArchiveView + + urlpatterns = patterns('', + # Example: /2012/week/23/ + url(r'^(?P\d{4})/week/(?P\d+)/$', + ArticleWeekArchiveView.as_view(), + name="archive_week"), + ) + + **Example myapp/article_archive_week.html**: + + .. code-block:: html+django + +

Week {{ week|date:'W' }}

+ +
    + {% for article in object_list %} +
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • + {% endfor %} +
+ +

+ {% if previous_week %} + Previous Week: {{ previous_week|date:"F Y" }} + {% endif %} + {% if previous_week and next_week %}--{% endif %} + {% if next_week %} + Next week: {{ next_week|date:"F Y" }} + {% endif %} +

+ + In this example, you are outputting the week number. The default + ``week_format`` in the ``WeekArchiveView`` uses week format ``'%U'`` + which is based on the United States week system where the week begins on a + Sunday. The ``'%W'`` format uses the ISO week format and its week + begins on a Monday. The ``'%W'`` format is the same in both the + :func:`~time.strftime` and the :tfilter:`date`. + + However, the :tfilter:`date` template filter does not have an equivalent + output format that supports the US based week system. The :tfilter:`date` + filter ``'%U'`` outputs the number of seconds since the Unix epoch. + DayArchiveView -------------- @@ -265,6 +455,53 @@ DayArchiveView * Uses a default ``template_name_suffix`` of ``_archive_day``. + **Example views.py**:: + + from django.views.generic.dates import DayArchiveView + + from myapp.models import Article + + class ArticleDayArchiveView(DayArchiveView): + queryset = Article.objects.all() + date_field = "pub_date" + make_object_list = True + allow_future = True + + **Example urls.py**:: + + from django.conf.urls import patterns, url + + from myapp.views import ArticleDayArchiveView + + urlpatterns = patterns('', + # Example: /2012/nov/10/ + url(r'^(?P\d{4})/(?P[-\w]+)/(?P\d+)/$', + ArticleDayArchiveView.as_view(), + name="archive_day"), + ) + + **Example myapp/article_archive_day.html**: + + .. code-block:: html+django + +

{{ day }}

+ +
    + {% for article in object_list %} +
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • + {% endfor %} +
+ +

+ {% if previous_day %} + Previous Day: {{ previous_day }} + {% endif %} + {% if previous_day and next_day %}--{% endif %} + {% if next_day %} + Next Day: {{ next_day }} + {% endif %} +

+ TodayArchiveView ---------------- @@ -289,6 +526,40 @@ TodayArchiveView * :class:`django.views.generic.dates.DateMixin` * :class:`django.views.generic.base.View` + **Notes** + + * Uses a default ``template_name_suffix`` of ``_archive_today``. + + **Example views.py**:: + + from django.views.generic.dates import TodayArchiveView + + from myapp.models import Article + + class ArticleTodayArchiveView(TodayArchiveView): + queryset = Article.objects.all() + date_field = "pub_date" + make_object_list = True + allow_future = True + + **Example urls.py**:: + + from django.conf.urls import patterns, url + + from myapp.views import ArticleTodayArchiveView + + urlpatterns = patterns('', + url(r'^today/$', + ArticleTodayArchiveView.as_view(), + name="archive_today"), + ) + + .. admonition:: Where is the example template for ``TodayArchiveView``? + + This view uses by default the same template as the + :class:`~DayArchiveView`, which is in the previous example. If you need + a different template, set the ``template_name`` attribute to be the + name of the new template. DateDetailView -------------- @@ -313,6 +584,32 @@ DateDetailView * :class:`django.views.generic.detail.SingleObjectMixin` * :class:`django.views.generic.base.View` + **Context** + + * Includes the single object associated with the ``model`` specified in + the ``DateDetailView``. + + **Notes** + + * Uses a default ``template_name_suffix`` of ``_detail``. + + **Example urls.py**:: + + from django.conf.urls import patterns, url + from django.views.generic.dates import DateDetailView + + urlpatterns = patterns('', + url(r'^(?P\d+)/(?P[-\w]+)/(?P\d+)/(?P\d+)/$', + DateDetailView.as_view(model=Article, date_field="pub_date"), + name="archive_date_detail"), + ) + + **Example myapp/article_detail.html**: + + .. code-block:: html+django + +

{{ object.title }}

+ .. note:: All of the generic views listed above have matching ``Base`` views that @@ -332,5 +629,3 @@ DateDetailView .. class:: BaseTodayArchiveView .. class:: BaseDateDetailView - - diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt index 01f9e32c53..7ce5c1d1be 100644 --- a/docs/ref/class-based-views/generic-editing.txt +++ b/docs/ref/class-based-views/generic-editing.txt @@ -12,9 +12,8 @@ editing content: .. 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`:: + Some of the examples on this page assume that an ``Article`` model has been + defined as follows in ``myapp/models.py``:: from django.core.urlresolvers import reverse from django.db import models