Implements zyga/django-pagination#22

[django-pagination.git] / doc / usage.rst

diff --git a/doc/usage.rst b/doc/usage.rst
index d875137..199e6a3 100644 (file)
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -9,15 +9,15 @@ How to use linaro-django-pagination
 ``linaro-django-pagination`` allows for easy Digg-style pagination without modifying
 your views.
 
-There are really 5 steps to setting it up with your projects (not including 
-installation, which is covered in INSTALL.txt in this same directory.)
+There are really 5 steps to setting it up with your projects (not including
+installation, which is covered in :ref:`installation`.)
 
 1. List this application in the ``INSTALLED_APPS`` portion of your settings
    file.  Your settings file might look something like::
    
        INSTALLED_APPS = (
            # ...
-           'pagination',
+           'linaro_django_pagination',
        )
 
 
@@ -26,7 +26,7 @@ installation, which is covered in INSTALL.txt in this same directory.)
    
        MIDDLEWARE_CLASSES = (
            # ...
-           'pagination.middleware.PaginationMiddleware',
+           'linaro_django_pagination.middleware.PaginationMiddleware',
        )
 
 3. If it's not already added in your setup, add the request context processor.
@@ -60,6 +60,14 @@ installation, which is covered in INSTALL.txt in this same directory.)
    
    Note that this replaces ``object_list`` with the list for the current page, so
    you can iterate over the ``object_list`` like you normally would.
+
+   If you are using template ``{% block %}`` tags, the autopaginate tag must
+   exist in the same ``{% block %}`` where you access the paginated
+   ``object_list``.
+
+   In general the full syntax is::
+
+        autopaginate QUERYSET [PAGINATE_BY] [ORPHANS] [as NAME]
    
 
 6. Now you want to display the current page and the available pages, so
@@ -67,7 +75,7 @@ installation, which is covered in INSTALL.txt in this same directory.)
    
        {% paginate %}
    
-   This does not take any arguments, but does assume that you have already
+   This does not require any arguments, but does assume that you have already
    called autopaginate, so make sure to do so first.
 
 
@@ -77,14 +85,33 @@ a way to navigate between the different pages--all without touching your views.
 Custom pagination templates
 ===========================
 
-In order to override the default pagination template use the extended form of
-the ``paginate`` tag::
+By default the objects will be paginated using a helper template
+"pagination/pagination.html". You can change this with an argument to
+``paginate``.
+
+In general the full syntax is::
+
+        paginate [using "TEMPLATE"]
+
+For example, to paginate posts on a hypothetical blog page you could use
+something like this::
 
     {% autopaginate posts pagesize %}
     {% paginate using "pagination/blog/post.html" %}
 
 The default pagination template is contained in the
-``pagination/pagination.html`` file inside the distribution.
+``pagination/pagination.html`` file inside the distribution. You could extend
+it and only customize the parts you care about. Please inspect the template to
+see the blocks it defines that you could customize.
+
+
+Multiple paginations per page
+=============================
+
+You can use autopaginate/paginate multiple times in the same template. The only
+requirement is to call autopaginate before calling paginate. That is, paginate
+acts on the most recent call to autopaginate.
+
 
 A Note About Uploads
 ====================
@@ -141,3 +168,7 @@ behavior of the pagination tags.  Here's an overview:
 ``PAGINATION_DISPLAY_DISABLED_NEXT_LINK``
     If set to ``False``, the next page link will not be displayed if there's no 
     next page. Defaults to False.
+
+``PAGINATION_DISABLE_LINK_FOR_FIRST_PAGE``
+    if set to ``False``, the first page will have ``?page=1`` link suffix in pagination displayed, otherwise is omitted.
+    Defaults to True.