From 6a037f63edf33e7a76f56828cf68bfae4ccb4f80 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 14 May 2013 11:27:03 +0100
Subject: Added OrderingFilter

---
 docs/api-guide/filtering.md | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md
index 94244301..7e99832e 100644
--- a/docs/api-guide/filtering.md
+++ b/docs/api-guide/filtering.md
@@ -190,7 +190,7 @@ The `SearchFilterBackend` class will only be applied if the view has a `search_f
         filter_backends = (filters.SearchFilter,)
         search_fields = ('username', 'email')
 
-This will allow the client to filter the itemss in the list by making queries such as:
+This will allow the client to filter the items in the list by making queries such as:
 
     http://example.com/api/users?search=russell
 
@@ -198,7 +198,7 @@ You can also perform a related lookup on a ForeignKey or ManyToManyField with th
 
     search_fields = ('username', 'email', 'profile__profession')
 
-By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma seperated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.
+By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.
 
 The search behavior may be restricted by prepending various characters to the `search_fields`.
 
@@ -214,6 +214,34 @@ For more details, see the [Django documentation][search-django-admin].
 
 ---
 
+## OrderingFilter
+
+The `OrderingFilter` class supports simple query parameter controlled ordering of results.  For example:
+
+    http://example.com/api/users?ordering=username
+
+The client may also specify reverse orderings by prefixing the field name with '-', like so:
+
+    http://example.com/api/users?ordering=-username
+
+Multiple orderings may also be specified:
+
+    http://example.com/api/users?ordering=account,username
+
+If an `ordering` attribute is set on the view, this will be used as the default ordering.
+
+Typicaly you'd instead control this by setting `order_by` on the initial queryset, but using the `ordering` parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template.  This makes it possible to automatically render column headers differently if they are being used to order the results.
+
+    class UserListView(generics.ListAPIView):
+        queryset = User.objects.all()
+        serializer = UserSerializer
+        filter_backends = (filters.OrderingFilter,)
+        ordering = ('username',) 
+
+The `ordering` attribute may be either a string or a list/tuple of strings.
+
+---
+
 # Custom generic filtering
 
 You can also provide your own generic filtering backend, or write an installable app for other developers to use.
-- 
cgit v1.2.3