diff options
Diffstat (limited to 'docs/pagination.txt')
| -rw-r--r-- | docs/pagination.txt | 121 |
1 files changed, 80 insertions, 41 deletions
diff --git a/docs/pagination.txt b/docs/pagination.txt index bfdf8eea1c..c36f56244f 100644 --- a/docs/pagination.txt +++ b/docs/pagination.txt @@ -59,28 +59,65 @@ page:: ... InvalidPage -Note that you can give ``Paginator`` a list/tuple or a Django ``QuerySet``. The -only difference is in implementation; if you pass a ``QuerySet``, the -``Paginator`` will call its ``count()`` method instead of using ``len()``, -because the former is more efficient. - ``Paginator`` objects ===================== +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 a ``EmptyPage`` error will be raised. + Methods ------- -``page(number)`` -- Returns a ``Page`` object with the given 1-based index. -Raises ``InvalidPage`` if the given page number doesn't exist. +``page(number)`` + Returns a ``Page`` object with the given 1-based index. Raises + ``InvalidPage`` if the given page number doesn't exist. Attributes ---------- -``count`` -- The total number of objects, across all pages. +In addition to the arguments above, which get stored as attributes, a +``Paginator`` object also has the following attributes: + +``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 ``object_list.__len__()``. This allows + objects, such as Django's ``QuerySet``, to use a more efficient ``count()`` + method when available. -``num_pages`` -- The total number of pages. +``num_pages`` + The total number of pages. -``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``. +``page_range`` + A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``. ``InvalidPage`` exceptions ========================== @@ -90,9 +127,12 @@ The ``page()`` method raises ``InvalidPage`` if the requested page is invalid the ``InvalidPage`` exception, but if you'd like more granularity, you can trap either of the following exceptions: -``PageNotAnInteger`` -- Raised when ``page()`` is given a value that isn't an integer. +``PageNotAnInteger`` + Raised when ``page()`` is given a value that isn't an integer. -``EmptyPage`` -- Raised when ``page()`` is given a valid value but no objects exist on that page. +``EmptyPage`` + Raised when ``page()`` is given a valid value but no objects exist on that + page. Both of the exceptions are subclasses of ``InvalidPage``, so you can handle them both with a simple ``except InvalidPage``. @@ -103,44 +143,43 @@ them both with a simple ``except InvalidPage``. Methods ------- -``has_next()`` -- Returns ``True`` if there's a next page. +``has_next()`` + Returns ``True`` if there's a next page. -``has_previous()`` -- Returns ``True`` if there's a previous page. +``has_previous()`` + Returns ``True`` if there's a previous page. -``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page. +``has_other_pages()`` + Returns ``True`` if there's a next *or* previous 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. +``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. -``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. +``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. -``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 -``start_index()`` would return ``3``. +``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 ``start_index()`` + would return ``3``. -``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 -``end_index()`` would return ``4``. +``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 ``end_index()`` + would return ``4``. Attributes ---------- -``object_list`` -- The list of objects on this page. - -``number`` -- The 1-based page number for this page. - -``paginator`` -- The associated ``Paginator`` object. +``object_list`` + The list of objects on this page. -The legacy ``ObjectPaginator`` class -==================================== +``number`` + The 1-based page number for this page. -The ``Paginator`` and ``Page`` classes are new in the Django development -version, as of revision 7306. In previous versions, Django provided an -``ObjectPaginator`` class that offered similar functionality but wasn't as -convenient. This class still exists, for backwards compatibility, but Django -now issues a ``DeprecationWarning`` if you try to use it. +``paginator`` + The associated ``Paginator`` object. |