Add simple HACKING file

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

diff --git a/docs/usage.txt b/docs/usage.txt
index 1a86b09..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 
@@ -68,3 +68,69 @@ 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.
+
+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
+--------------------
+
+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 
+as late as possible in your views.
+
+
+Optional Settings
+------------------
+
+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:
+
+``PAGINATION_DEFAULT_PAGINATION``
+    The default amount of items to show on a page if no number is specified.
+
+``PAGINATION_DEFAULT_WINDOW``
+    The number of items to the left and to the right of the current page to
+    display (accounting for ellipses).
+
+``PAGINATION_DEFAULT_ORPHANS``
+    The number of orphans allowed.  According to the Django documentation,
+    orphans are defined as::
+    
+        The minimum number of items allowed on the last page, defaults to zero.
+
+``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.
+
+``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.