From 7c23fbd9a0cb0f41abcf4a75a4708dc140f99ace Mon Sep 17 00:00:00 2001 From: Simon Meers Date: Mon, 6 Dec 2010 23:09:55 +0000 Subject: [PATCH] [1.2.X] Fixed #8975 -- documented related order methods -- thanks to Leo for the report and dwillis for the initial patch. Backport of r14848 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14849 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/options.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 3dfcdfffbceda..1b04c4698c987 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -143,6 +143,32 @@ do this:: class Meta: order_with_respect_to = 'question' +When ``order_with_respect_to`` is set, two additional methods are provided to +retrieve and to set the order of the related objects: ``get_RELATED_order()`` +and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For +example, assuming that a ``Question`` object has multiple related ``Answer`` +objects, the list returned contains the primary keys of the related ``Answer`` +objects:: + + >>> question = Question.objects.get(id=1) + >>> question.get_answer_order() + [1, 2, 3] + +The order of a ``Question`` object's related ``Answer`` objects can be set by +passing in a list of ``Answer`` primary keys:: + + >>> question.set_answer_order([3, 1, 2]) + +The related objects also get two methods, ``get_next_in_order()`` and +``get_previous_in_order()``, which can be used to access those objects in their +proper order. Assuming the ``Answer`` objects are ordered by ``id``:: + + >>> answer = Answer.objects.get(id=2) + >>> answer.get_next_in_order() + + >>> answer.get_previous_in_order() + + ``ordering`` ------------