.. _views:

==============
Birdland Views
==============


Birdland provides configurable views for displaying collections of posts,
including latest lists, date-based archives, by author archives, by tag
archives, as well as views for displaying post details. These views are 
organized into submodules of the ``birdland.views`` package. Here is a list of
these views and their use.


``object_list.object_list``
===========================

A replacement for ``django.views.generic.list_detail.object_list`` which accepts 
``list`` objects in addition to ``QuerySet`` objects.

Templates: ``<app_label>/<model_name>_list.html``

Context:
    object_list
        list of objects
    is_paginated
        are the results paginated?
    results_per_page
        number of objects per page (if paginated)
    has_next
        is there a next page?
    has_previous
        is there a previous page?
    page
        the current page
    next
        the next page
    previous
        the previous page
    pages
        number of pages, total
    hits
        number of objects, total
    last_on_page
        the result number of the last of object in the object_list (1-indexed)
    first_on_page
        the result number of the first object in the object_list (1-indexed)
    page_range
        a list of the page numbers (1-indexed).
    paginator
        a ``django.core.paginator.Paginator`` object
    page_obj
        a ``django.core.paginator.Page`` object representing the current result
        page generated by ``paginator``


``date_based.archive_index``
============================

Generic top-level archive of date-based objects.

A replacement for ``django.views.generic.date_based.archive_index``
which offers result-set pagination.

Templates: ``<app_label>/<model_name>_archive.html``

Context:
    date_list
        List of years
    latest
        Latest N (defaults to 15) objects by date
    paginator
       ``django.core.paginator.Paginator`` object
       (if ``num_latest`` provided)
    page_obj
       ``django.core.paginator.Page`` object
       (if ``num_latest`` provided)


``date_based.archive_year``
===========================

Generic yearly archive view.

A replacement for ``django.views.generic.date_based.archive_year``
which offers result-set pagination.

Templates: ``<app_label>/<model_name>_archive_year.html``

Context:
    date_list
        List of months in this year with objects
    year
        This year
    object_list
        List of objects published in the given month
        (Only available if make_object_list argument is True)
    paginator
        ``django.core.paginator.Paginator`` object
        (Only available if make_object_list argument is True)
    page_obj
        ``django.core.paginator.Page`` object
        (Only available if make_object_list argument is True)



``date_based.archive_month``
============================

Generic monthly archive view.

A replacement for ``django.views.generic.date_based.archive_month``
which offers result-set pagination.

Templates: ``<app_label>/<model_name>_archive_month.html``

Context:
    month:
        (date) this month
    next_month:
        (date) the first day of the next month, or None if the next month is in the future
    previous_month:
        (date) the first day of the previous month
    object_list:
        list of objects published in the given month
    paginator:
        ``django.core.paginator.Paginator`` object
        (Available only if paginate_by and page provided)
    page_obj:
        ``django.core.paginator.Page`` object
        (Available only if paginate_by and page provided)


``date_based.archive_week``
===========================

Generic weekly archive view.

A replacement for ``django.views.generic.date_based.archive_week``
which offers result-set pagination.

Templates: ``<app_label>/<model_name>_archive_week.html``

Context:
    week:
        (date) this week
    object_list:
        list of objects published in the given week
    paginator:
        ``django.core.paginator.Paginator`` object
        (Available only if paginate_by and page are provided)
    page_obj:
        ``django.core.paginator.Page`` object
        (Available only if paginate_by and page are provided)


``date_based.archive_day``
==========================

Generic daily archive view.

A replacement for ``django.views.generic.date_based.archive_day``
which offers result-set pagination.

Templates: ``<app_label>/<model_name>_archive_day.html``

Context:
    object_list:
        list of objects published that day
    day:
        (datetime) the day
    previous_day
        (datetime) the previous day
    next_day
        (datetime) the next day, or None if the current day is today
    paginator:
        ``django.core.paginator.Paginator`` object
        (Available only if paginate_by and page are provided)
    page_obj:
        ``django.core.paginator.Page`` object
        (Available only if paginate_by and page are provided)


``public.author_list``
======================

A wrapper around ``birdland.views.object_list.object_list`` which
creates a ``QuerySet`` of all ``django.contrib.auth.models.User``
objects associated with all published ``Entry`` which is passed
to ``birdland.views.object_list.object_list``.

Templates: ``birdland/author_list.html``

Context:
    author_list
        list of ``django.contrib.auth.models.User`` objects


``public.entry_archive_author``
===============================

A wrapper around ``birdland.views.object_list.object_list`` which
creates a ``QuerySet`` of all published ``Entry`` objects for which
the ``django.contrib.auth.models.User`` retrieved by ``username`` is
the ``author``.

Templates: ``birdland/entry_archive_author.html``

Context:
    entry_list
        list of ``Entry`` objects

    author
        the ``auth.User`` object for the author


``public.entry_detail``
=======================

A wrapper around ``django.views.generic.list_detail.object_detail``
which passes ``object_detail`` a ``QuerySet`` of all published
entries and an ``Entry`` slug.

Templates: ``birdland/entry_detail.html``

Context:
    entry
        the ``Entry`` object

``public.entry_list``
=====================

A wrapper around ``birdland.views.object_list.object_list`` which
passes ``object_list`` a ``QuerySet`` of all published ``Entry``
objects.

Templates: ``birdland/entry_list.html``

Context:
    entry_list
        list of ``Entry`` objects


``public.entry_archive_year``
=============================

A wrapper around ``birdland.views.date_based.archive_year`` which
passes ``archive_year`` a ``QuerySet`` of all published ``Entry``
objects.

Templates: ``birdland/entry_archive_year.html``

Context:
    entry_list
        list of ``Entry`` objects

``public.entry_archive_month``
==============================

A wrapper around ``birdland.views.date_based.archive_month`` which
passes ``archive_month`` a ``QuerySet`` of all published ``Entry``
objects.

Templates: ``birdland/entry_archive_month.html``

Context:
    entry_list
        list of ``Entry`` objects


``public.entry_archive_week``
=============================

A wrapper around ``birdland.views.date_based.archive_week`` which
passes ``archive_week`` a ``QuerySet`` of all published ``Entry``
objects.

Templates: ``birdland/entry_archive_week.html``

Context:
    entry_list
        list of ``Entry`` objects


``public.entry_archive_day``
============================

A wrapper around ``birdland.views.date_based.archive_day`` which
passes ``archive_day`` a ``QuerySet`` of all published ``Entry``
objects.

Templates: ``birdland/entry_archive_day.html``

Context:
    entry_list
        list of ``Entry`` objects


``public.entry_archive_today``
==============================

Returns ``entry_archive_day`` with today's date.


``public.entry_archive_detail``
===============================

Returns ``django.views.generic.date_based.object_detail`` with appropriate defaults.
    
``public.entry_archive_tag``
============================

A wrapper around ``tagging.views.tagged_object_list`` which
passes ``tagged_object_list`` a ``QuerySet`` of all published
``Entry`` objects.

Templates: ``birdland/entry_archive_tag.html``

Context:
    entry_list
        list of ``Entry`` objects


``public.entry_tag_list``
=========================

A wrapper around ``birdland.views.object_list.object_list`` which
passes a ``list`` of all ``tagging.models.Tag`` objects associated
with published ``Entry`` objects.

Templates: ``birdland/entry_tag_list.html``

Context:
    tag_list
        list of ``tagging.models.Tag`` objects

