Add simple HACKING file

[django-pagination.git] / docs / usage.txt

diff --git a/docs/usage.txt b/docs/usage.txt
index b520169..756787d 100644 (file)
--- a/docs/usage.txt
+++ b/docs/usage.txt
@@ -1,7 +1,7 @@
-How to use django-pagination
+How to use linaro-django-pagination

 ----------------------------
 
 ----------------------------
 

-``django-pagination`` allows for easy Digg-style pagination without modifying
+``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 
 your views.
 
 There are really 5 steps to setting it up with your projects (not including 


@@ -69,11 +69,24 @@ installation, which is covered in INSTALL.txt in this same directory.)
 That's it!  You have now paginated ``object_list`` and given users of the site
 a way to navigate between the different pages--all without touching your views.
 
 That's it!  You have now paginated ``object_list`` and given users of the site
 a way to navigate between the different pages--all without touching your views.
 

+Custom pagination templates
+---------------------------
+
+In order to override the default pagination template, declare a context variable 
+named ``pagination_template`` set to the template name::
+
+    {% with 'pagination/blog/post.html' as pagination_template %}
+        {% autopaginate posts pagesize %}
+        {% paginate %}
+    {% endwith %}
+
+The default pagination template is contained in the ``pagination/default.html`` 
+file inside the distribution.

 
 A Note About Uploads
 --------------------
 
 
 A Note About Uploads
 --------------------
 

-It is important, when using django-pagination in conjunction with file uploads,
+It is important, when using linaro-django-pagination in conjunction with file uploads,

 to be aware of when ``request.page`` is accessed.  As soon as ``request.page``
 is accessed, ``request.upload_handlers`` is frozen and cannot be altered in any
 way.  It's a good idea to access the ``page`` attribute on the request object 
 to be aware of when ``request.page`` is accessed.  As soon as ``request.page``
 is accessed, ``request.upload_handlers`` is frozen and cannot be altered in any
 way.  It's a good idea to access the ``page`` attribute on the request object 


@@ -83,7 +96,7 @@ as late as possible in your views.
 Optional Settings
 ------------------
 
 Optional Settings
 ------------------
 

-In django-pagination, there are no required settings.  There are, however, a
+In linaro-django-pagination, there are no required settings.  There are, however, a

 small set of optional settings useful for changing the default behavior of the
 pagination tags.  Here's an overview:
 
 small set of optional settings useful for changing the default behavior of the
 pagination tags.  Here's an overview:
 


@@ -103,4 +116,21 @@ pagination tags.  Here's an overview:
 ``PAGINATION_INVALID_PAGE_RAISES_404``
     Determines whether an invalid page raises an ``Http404`` or just sets the
     ``invalid_page`` context variable.  ``True`` does the former and ``False``
 ``PAGINATION_INVALID_PAGE_RAISES_404``
     Determines whether an invalid page raises an ``Http404`` or just sets the
     ``invalid_page`` context variable.  ``True`` does the former and ``False``

-    does the latter.
\ No newline at end of file
+    does the latter.
+
+``DISPLAY_PAGE_LINKS``
+    If set to ``False``, links for single pages will not be displayed.
+
+``PREVIOUS_LINK_DECORATOR``
+    An HTML prefix for the previous page link; the default value is ``‹‹ ``.
+
+``NEXT_LINK_DECORATOR``
+    An HTML postfix for the next page link; the default value is `` ››``.
+
+``DISPLAY_DISABLED_PREVIOUS_LINK``
+    If set to ``False``, the previous page link will not be displayed if there's 
+    no previous page.
+
+``DISPLAY_DISABLED_NEXT_LINK``
+    If set to ``False``, the next page link will not be displayed if there's no 
+    next page.