lib/django-1.4/docs/topics/pagination.txt - external/googleappengine/python - Git at Google

 ==========
 Pagination
 ==========

 .. module:: django.core.paginator
    :synopsis: Classes to help you easily manage paginated data.

 Django provides a few classes that help you manage paginated data -- that is,
 data that's split across several pages, with "Previous/Next" links. These
 classes live in :file:`django/core/paginator.py`.

 Example
 =======

 Give :class:`Paginator` a list of objects, plus the number of items you'd like to
 have on each page, and it gives you methods for accessing the items for each
 page::

     >>> from django.core.paginator import Paginator
     >>> objects = ['john', 'paul', 'george', 'ringo']
     >>> p = Paginator(objects, 2)

     >>> p.count
     4
     >>> p.num_pages
     2
     >>> p.page_range
     [1, 2]

     >>> page1 = p.page(1)
     >>> page1
     <Page 1 of 2>
     >>> page1.object_list
     ['john', 'paul']

     >>> page2 = p.page(2)
     >>> page2.object_list
     ['george', 'ringo']
     >>> page2.has_next()
     False
     >>> page2.has_previous()
     True
     >>> page2.has_other_pages()
     True
     >>> page2.next_page_number()
     3
     >>> page2.previous_page_number()
     1
     >>> page2.start_index() # The 1-based index of the first item on this page
     3
     >>> page2.end_index() # The 1-based index of the last item on this page
     4

     >>> p.page(0)
     Traceback (most recent call last):
     ...
     EmptyPage: That page number is less than 1
     >>> p.page(3)
     Traceback (most recent call last):
     ...
     EmptyPage: That page contains no results

 .. note::

     Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``,
     or any other object with a ``count()`` or ``__len__()`` method. When
     determining the number of objects contained in the passed object,
     ``Paginator`` will first try calling ``count()``, then fallback to using
     ``len()`` if the passed object has no ``count()`` method. This allows
     objects such as Django's ``QuerySet`` to use a more efficient ``count()``
     method when available.


 Using ``Paginator`` in a view
 ==============================

 Here's a slightly more complex example using :class:`Paginator` in a view to
 paginate a queryset. We give both the view and the accompanying template to
 show how you can display the results. This example assumes you have a
 ``Contacts`` model that has already been imported.

 The view function looks like this::

     from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger

     def listing(request):
         contact_list = Contacts.objects.all()
         paginator = Paginator(contact_list, 25) # Show 25 contacts per page

         page = request.GET.get('page')
         try:
             contacts = paginator.page(page)
         except PageNotAnInteger:
             # If page is not an integer, deliver first page.
             contacts = paginator.page(1)
         except EmptyPage:
             # If page is out of range (e.g. 9999), deliver last page of results.
             contacts = paginator.page(paginator.num_pages)

         return render_to_response('list.html', {"contacts": contacts})

 In the template :file:`list.html`, you'll want to include navigation between
 pages along with any interesting information from the objects themselves::

     {% for contact in contacts %}
         {# Each "contact" is a Contact model object. #}
         {{ contact.full_name|upper }}<br />
         ...
     {% endfor %}

     <div class="pagination">
         <span class="step-links">
             {% if contacts.has_previous %}
                 <a href="?page={{ contacts.previous_page_number }}">previous</a>
             {% endif %}

             <span class="current">
                 Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
             </span>

             {% if contacts.has_next %}
                 <a href="?page={{ contacts.next_page_number }}">next</a>
             {% endif %}
         </span>
     </div>

 .. versionchanged:: 1.4
     Previously, you would need to use
     ``{% for contact in contacts.object_list %}``, since the ``Page``
     object was not iterable.


 ``Paginator`` objects
 =====================

 The :class:`Paginator` class has this constructor:

 .. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)

 Required arguments
 ------------------

 ``object_list``
     A list, tuple, Django ``QuerySet``, or other sliceable object with a
     ``count()`` or ``__len__()`` method.

 ``per_page``
     The maximum number of items to include on a page, not including orphans
     (see the ``orphans`` optional argument below).

 Optional arguments
 ------------------

 ``orphans``
     The minimum number of items allowed on the last page, defaults to zero.
     Use this when you don't want to have a last page with very few items.
     If the last page would normally have a number of items less than or equal
     to ``orphans``, then those items will be added to the previous page (which
     becomes the last page) instead of leaving the items on a page by
     themselves. For example, with 23 items, ``per_page=10``, and
     ``orphans=3``, there will be two pages; the first page with 10 items and
     the  second (and last) page with 13 items.

 ``allow_empty_first_page``
     Whether or not the first page is allowed to be empty.  If ``False`` and
     ``object_list`` is  empty, then an ``EmptyPage`` error will be raised.

 Methods
 -------

 .. method:: Paginator.page(number)

     Returns a :class:`Page` object with the given 1-based index. Raises
     :exc:`InvalidPage` if the given page number doesn't exist.

 Attributes
 ----------

 .. attribute:: Paginator.count

     The total number of objects, across all pages.

     .. note::

         When determining the number of objects contained in ``object_list``,
         ``Paginator`` will first try calling ``object_list.count()``. If
         ``object_list`` has no ``count()`` method, then ``Paginator`` will
         fallback to using ``len(object_list)``. This allows objects, such as
         Django's ``QuerySet``, to use a more efficient ``count()`` method when
         available.

 .. attribute:: Paginator.num_pages

     The total number of pages.

 .. attribute:: Paginator.page_range

     A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.


 ``InvalidPage`` exceptions
 ==========================

 .. exception:: InvalidPage

 	A base class for exceptions raised when a paginator is passed an invalid
 	page number.

 The :meth:`Paginator.page` method raises an exception if the requested page is
 invalid (i.e., not an integer) or contains no objects. Generally, it's enough
 to trap the ``InvalidPage`` exception, but if you'd like more granularity, you
 can trap either of the following exceptions:

 .. exception:: PageNotAnInteger

     Raised when ``page()`` is given a value that isn't an integer.

 .. exception:: EmptyPage

     Raised when ``page()`` is given a valid value but no objects exist on that
     page.

 Both of the exceptions are subclasses of :exc:`InvalidPage`, so you can handle
 them both with a simple ``except InvalidPage``.


 ``Page`` objects
 ================

 You usually won't construct ``Page`` objects by hand -- you'll get them
 using :meth:`Paginator.page`.

 .. class:: Page(object_list, number, paginator)

 .. versionadded:: 1.4
     A page acts like a sequence of :attr:`Page.object_list` when using
     ``len()`` or iterating it directly.

 Methods
 -------

 .. method:: Page.has_next()

     Returns ``True`` if there's a next page.

 .. method:: Page.has_previous()

     Returns ``True`` if there's a previous page.

 .. method:: Page.has_other_pages()

     Returns ``True`` if there's a next *or* previous page.

 .. method:: Page.next_page_number()

     Returns the next page number. Note that this is "dumb" and will return the
     next page number regardless of whether a subsequent page exists.

 .. method:: Page.previous_page_number()

     Returns the previous page number. Note that this is "dumb" and will return
     the previous page number regardless of whether a previous page exists.

 .. method:: Page.start_index()

     Returns the 1-based index of the first object on the page, relative to all
     of the objects in the paginator's list. For example, when paginating a list
     of 5 objects with 2 objects per page, the second page's
     :meth:`~Page.start_index` would return ``3``.

 .. method:: Page.end_index()

     Returns the 1-based index of the last object on the page, relative to all
     of the objects in the paginator's list. For example, when paginating a list
     of 5 objects with 2 objects per page, the second page's
     :meth:`~Page.end_index` would return ``4``.

 Attributes
 ----------

 .. attribute:: Page.object_list

     The list of objects on this page.

 .. attribute:: Page.number

     The 1-based page number for this page.

 .. attribute:: Page.paginator

     The associated :class:`Paginator` object.
	==========
	Pagination
	==========

	.. module:: django.core.paginator
	:synopsis: Classes to help you easily manage paginated data.

	Django provides a few classes that help you manage paginated data -- that is,
	data that's split across several pages, with "Previous/Next" links. These
	classes live in :file:`django/core/paginator.py`.

	Example
	=======

	Give :class:`Paginator` a list of objects, plus the number of items you'd like to
	have on each page, and it gives you methods for accessing the items for each
	page::

	>>> from django.core.paginator import Paginator
	>>> objects = ['john', 'paul', 'george', 'ringo']
	>>> p = Paginator(objects, 2)

	>>> p.count
	4
	>>> p.num_pages
	2
	>>> p.page_range
	[1, 2]

	>>> page1 = p.page(1)
	>>> page1
	<Page 1 of 2>
	>>> page1.object_list
	['john', 'paul']

	>>> page2 = p.page(2)
	>>> page2.object_list
	['george', 'ringo']
	>>> page2.has_next()
	False
	>>> page2.has_previous()
	True
	>>> page2.has_other_pages()
	True
	>>> page2.next_page_number()
	3
	>>> page2.previous_page_number()
	1
	>>> page2.start_index() # The 1-based index of the first item on this page
	3
	>>> page2.end_index() # The 1-based index of the last item on this page
	4

	>>> p.page(0)
	Traceback (most recent call last):
	...
	EmptyPage: That page number is less than 1
	>>> p.page(3)
	Traceback (most recent call last):
	...
	EmptyPage: That page contains no results

	.. note::

	Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``,
	or any other object with a ``count()`` or ``__len__()`` method. When
	determining the number of objects contained in the passed object,
	``Paginator`` will first try calling ``count()``, then fallback to using
	``len()`` if the passed object has no ``count()`` method. This allows
	objects such as Django's ``QuerySet`` to use a more efficient ``count()``
	method when available.


	Using ``Paginator`` in a view
	==============================

	Here's a slightly more complex example using :class:`Paginator` in a view to
	paginate a queryset. We give both the view and the accompanying template to
	show how you can display the results. This example assumes you have a
	``Contacts`` model that has already been imported.

	The view function looks like this::

	from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger

	def listing(request):
	contact_list = Contacts.objects.all()
	paginator = Paginator(contact_list, 25) # Show 25 contacts per page

	page = request.GET.get('page')
	try:
	contacts = paginator.page(page)
	except PageNotAnInteger:
	# If page is not an integer, deliver first page.
	contacts = paginator.page(1)
	except EmptyPage:
	# If page is out of range (e.g. 9999), deliver last page of results.
	contacts = paginator.page(paginator.num_pages)

	return render_to_response('list.html', {"contacts": contacts})

	In the template :file:`list.html`, you'll want to include navigation between
	pages along with any interesting information from the objects themselves::

	{% for contact in contacts %}
	{# Each "contact" is a Contact model object. #}
	{{ contact.full_name\|upper }}<br />
	...
	{% endfor %}

	<div class="pagination">
	<span class="step-links">
	{% if contacts.has_previous %}
	<a href="?page={{ contacts.previous_page_number }}">previous</a>
	{% endif %}

	<span class="current">
	Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
	</span>

	{% if contacts.has_next %}
	<a href="?page={{ contacts.next_page_number }}">next</a>
	{% endif %}
	</span>
	</div>

	.. versionchanged:: 1.4
	Previously, you would need to use
	``{% for contact in contacts.object_list %}``, since the ``Page``
	object was not iterable.


	``Paginator`` objects
	=====================

	The :class:`Paginator` class has this constructor:

	.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)

	Required arguments
	------------------

	``object_list``
	A list, tuple, Django ``QuerySet``, or other sliceable object with a
	``count()`` or ``__len__()`` method.

	``per_page``
	The maximum number of items to include on a page, not including orphans
	(see the ``orphans`` optional argument below).

	Optional arguments
	------------------

	``orphans``
	The minimum number of items allowed on the last page, defaults to zero.
	Use this when you don't want to have a last page with very few items.
	If the last page would normally have a number of items less than or equal
	to ``orphans``, then those items will be added to the previous page (which
	becomes the last page) instead of leaving the items on a page by
	themselves. For example, with 23 items, ``per_page=10``, and
	``orphans=3``, there will be two pages; the first page with 10 items and
	the second (and last) page with 13 items.

	``allow_empty_first_page``
	Whether or not the first page is allowed to be empty. If ``False`` and
	``object_list`` is empty, then an ``EmptyPage`` error will be raised.

	Methods
	-------

	.. method:: Paginator.page(number)

	Returns a :class:`Page` object with the given 1-based index. Raises
	:exc:`InvalidPage` if the given page number doesn't exist.

	Attributes
	----------

	.. attribute:: Paginator.count

	The total number of objects, across all pages.

	.. note::

	When determining the number of objects contained in ``object_list``,
	``Paginator`` will first try calling ``object_list.count()``. If
	``object_list`` has no ``count()`` method, then ``Paginator`` will
	fallback to using ``len(object_list)``. This allows objects, such as
	Django's ``QuerySet``, to use a more efficient ``count()`` method when
	available.

	.. attribute:: Paginator.num_pages

	The total number of pages.

	.. attribute:: Paginator.page_range

	A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.


	``InvalidPage`` exceptions
	==========================

	.. exception:: InvalidPage

	A base class for exceptions raised when a paginator is passed an invalid
	page number.

	The :meth:`Paginator.page` method raises an exception if the requested page is
	invalid (i.e., not an integer) or contains no objects. Generally, it's enough
	to trap the ``InvalidPage`` exception, but if you'd like more granularity, you
	can trap either of the following exceptions:

	.. exception:: PageNotAnInteger

	Raised when ``page()`` is given a value that isn't an integer.

	.. exception:: EmptyPage

	Raised when ``page()`` is given a valid value but no objects exist on that
	page.

	Both of the exceptions are subclasses of :exc:`InvalidPage`, so you can handle
	them both with a simple ``except InvalidPage``.


	``Page`` objects
	================

	You usually won't construct ``Page`` objects by hand -- you'll get them
	using :meth:`Paginator.page`.

	.. class:: Page(object_list, number, paginator)

	.. versionadded:: 1.4
	A page acts like a sequence of :attr:`Page.object_list` when using
	``len()`` or iterating it directly.

	Methods
	-------

	.. method:: Page.has_next()

	Returns ``True`` if there's a next page.

	.. method:: Page.has_previous()

	Returns ``True`` if there's a previous page.

	.. method:: Page.has_other_pages()

	Returns ``True`` if there's a next or previous page.

	.. method:: Page.next_page_number()

	Returns the next page number. Note that this is "dumb" and will return the
	next page number regardless of whether a subsequent page exists.

	.. method:: Page.previous_page_number()

	Returns the previous page number. Note that this is "dumb" and will return
	the previous page number regardless of whether a previous page exists.

	.. method:: Page.start_index()

	Returns the 1-based index of the first object on the page, relative to all
	of the objects in the paginator's list. For example, when paginating a list
	of 5 objects with 2 objects per page, the second page's
	:meth:`~Page.start_index` would return ``3``.

	.. method:: Page.end_index()

	Returns the 1-based index of the last object on the page, relative to all
	of the objects in the paginator's list. For example, when paginating a list
	of 5 objects with 2 objects per page, the second page's
	:meth:`~Page.end_index` would return ``4``.

	Attributes
	----------

	.. attribute:: Page.object_list

	The list of objects on this page.

	.. attribute:: Page.number

	The 1-based page number for this page.

	.. attribute:: Page.paginator

	The associated :class:`Paginator` object.