From 8d1d99018725469061d5696a5552e7ebdb5cccc9 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 1 Oct 2012 16:17:01 +0100
Subject: Pagination docs

---
 docs/api-guide/pagination.md | 18 ++++++++++++------
 docs/index.md                |  2 ++
 docs/static/css/default.css  |  4 ++--
 docs/template.html           |  5 +++--
 4 files changed, 19 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md
index 0f0a32b5..6211a0ac 100644
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@@ -8,7 +8,7 @@
 
 REST framework includes a `PaginationSerializer` class that makes it easy to return paginated data in a way that can then be rendered to arbitrary media types. 
 
-## Examples
+## Paginating basic data
 
 Let's start by taking a look at an example from the Django documentation.
 
@@ -35,6 +35,8 @@ The `context` argument of the `PaginationSerializer` class may optionally includ
 
 We could now return that data in a `Response` object, and it would be rendered into the correct media type.
 
+## Paginating QuerySets
+
 Our first example worked because we were using primative objects.  If we wanted to paginate a queryset or other complex data, we'd need to specify a serializer to use to serialize the result set itself with.
 
 We can do this using the `object_serializer_class` attribute on the inner `Meta` class of the pagination serializer.  For example.
@@ -83,16 +85,20 @@ You can also set the pagination style on a per-view basis, using the `ListAPIVie
         pagination_serializer_class = CustomPaginationSerializer
         paginate_by = 10
 
+For more complex requirements such as serialization that differs depending on the requested media type you can override the `.get_paginate_by()` and `.get_pagination_serializer_class()` methods.
+
 ## Creating custom pagination serializers
 
-Override `pagination.BasePaginationSerializer`, and set the fields that you want the serializer to return.
+To create a custom pagination serializer class you should override `pagination.BasePaginationSerializer` and set the fields that you want the serializer to return.
+
+For example, to nest a pair of links labelled 'prev' and 'next' you might use something like this.
 
-For example.
+    class LinksSerializer(serializers.Serializer):
+        next = pagination.NextURLField(source='*')
+        prev = pagination.PreviousURLField(source='*')
 
     class CustomPaginationSerializer(pagination.BasePaginationSerializer):
-        next = pagination.NextURLField()
+        links = LinksSerializer(source='*')  # Takes the page object as the source
         total_results = serializers.Field(source='paginator.count')
 
-
 [cite]: https://docs.djangoproject.com/en/dev/topics/pagination/
-
diff --git a/docs/index.md b/docs/index.md
index e7db5dbc..92afbea8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -85,6 +85,7 @@ The API guide is your complete reference manual to all the functionality provide
 * [Authentication][authentication]
 * [Permissions][permissions]
 * [Throttling][throttling]
+* [Pagination][pagination]
 * [Content negotiation][contentnegotiation]
 * [Format suffixes][formatsuffixes]
 * [Returning URLs][reverse]
@@ -161,6 +162,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [authentication]: api-guide/authentication.md
 [permissions]: api-guide/permissions.md
 [throttling]: api-guide/throttling.md
+[pagination]: api-guide/pagination.md
 [contentnegotiation]: api-guide/content-negotiation.md
 [formatsuffixes]: api-guide/format-suffixes.md
 [reverse]: api-guide/reverse.md
diff --git a/docs/static/css/default.css b/docs/static/css/default.css
index 213a700e..49aac3a3 100644
--- a/docs/static/css/default.css
+++ b/docs/static/css/default.css
@@ -36,14 +36,14 @@ pre {
 }
 
 /* GitHub 'Star' badge */
-body.index #main-content iframe {
+body.index-page #main-content iframe {
     float: right;
     margin-top: -12px;
     margin-right: -15px;
 }
 
 /* Travis CI badge */
-body.index #main-content p:first-of-type {
+body.index-page #main-content p:first-of-type {
     float: right;
     margin-right: 8px;
     margin-top: -14px;
diff --git a/docs/template.html b/docs/template.html
index 4ac94f40..fbd30159 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -16,7 +16,7 @@
     <!--[if lt IE 9]>
       <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
     <![endif]-->
-  <body onload="prettyPrint()" class="{{ page_id }}">
+  <body onload="prettyPrint()" class="{{ page_id }}-page">
 
     <div class="navbar navbar-inverse navbar-fixed-top">
       <div class="navbar-inner">
@@ -55,6 +55,7 @@
                   <li><a href="{{ base_url }}/api-guide/authentication{{ suffix }}">Authentication</a></li>
                   <li><a href="{{ base_url }}/api-guide/permissions{{ suffix }}">Permissions</a></li>
                   <li><a href="{{ base_url }}/api-guide/throttling{{ suffix }}">Throttling</a></li>
+                  <li><a href="{{ base_url }}/api-guide/pagination{{ suffix }}">Pagination</a></li>
                   <li><a href="{{ base_url }}/api-guide/content-negotiation{{ suffix }}">Content negotiation</a></li>
                   <li><a href="{{ base_url }}/api-guide/format-suffixes{{ suffix }}">Format suffixes</a></li>
                   <li><a href="{{ base_url }}/api-guide/reverse{{ suffix }}">Returning URLs</a></li>
@@ -122,4 +123,4 @@
         event.stopPropagation();
       });
     </script>
-</body></html>
\ No newline at end of file
+</body></html>
-- 
cgit v1.2.3