/docs/managers.txt
Plain Text | 104 lines | 78 code | 26 blank | 0 comment | 0 complexity | 0821faff32656fafd46550c034e16e9d MD5 | raw file
Possible License(s): BSD-3-Clause
1============================================ 2Custom manager for models which use comments 3============================================ 4 5 6It's relatively common, when a model will be making use of the comment 7system, to want to perform a query for the "most commented" or "most 8discussed" objects of that model -- those objects which have received 9the most comments. To make this easier, ``comment_utils`` provides a 10custom manager which includes a generic method for performing this 11query. 12 13 14``comment_utils.managers.CommentedObjectManager`` 15------------------------------------------------- 16 17This is a simple custom manager which can query for the "most 18commented" objects of the model it's attached to. This is accomplished 19through a single method named ``most_commented``, which takes the 20following keyword arguments:: 21 22 num 23 The maximum number of objects to return. Defaults to 5 if not 24 supplied. 25 26 free 27 If ``True``, will query for objects with the most 28 ``FreeComment`` objects (unregistered comments) attached to 29 them; if ``False``, will query for objects with the most 30 ``Comment`` objects (registered comments) attached to 31 them. Defaults to ``True`` if not supplied. 32 33Because the order of the objects -- objects with higher comment counts 34should come first -- is important, this method returns a list rather 35than a ``QuerySet``. Each item in the returned list will be a 36dictionary with the following keys:: 37 38 object 39 An object of the model the ``CommentedObjectManager`` is 40 attached to. 41 42 comment_count 43 The number of comments on that object. 44 45There are two primary ways to make use of this manager: 46 471. When you have a model which will be making use of comments, but 48 would not otherwise have a custom manager. 49 502. When you have a model which will be making use of comments, but 51 will need a custom manager to add functionality specific to that 52 model. 53 54To show how to use ``CommentedObjectManager`` in either case, we'll 55use the following example model, which might represent entries in a 56weblog. 57 58 from django.db import models 59 60 STATUS_CHOICES = ( 61 (1, 'Live'), 62 (2, 'Hidden'), 63 ) 64 65 class Entry(models.Model): 66 title = models.CharField(maxlength=250) 67 pub_date = models.DateTimeField() 68 body = models.TextField() 69 status = models.IntegerField(choices=STATUS_CHOICES) 70 71If the ``Entry`` model wants to use comments, but you wouldn't 72otherwise want a custom manager on it, adding 73``CommentedObjectManager`` is just a two-line change; add the 74following at the top of the models file:: 75 76 from comment_utils.managers import CommentedObjectManager 77 78And then inside the ``Entry`` class add this line:: 79 80 objects = CommentedObjectManager() 81 82This will override the automatic manager assigned by Django, so that 83``Entry.objects`` will be an instance of ``CommentedObjectManager``; 84all the usual manager methods (``all``, ``filter``, etc.) will still 85work, but ``Entry.objects.most_commented()`` will also be available. 86 87If the ``Entry`` model should also have its own custom manager -- say, 88to enable automatic filtering out of "hidden" entries in order to 89avoid displaying them -- then that manager should subclass 90``CommentedObjectManager`` instead of Django's base ``Manager`` 91class. The implementation might look like this:: 92 93 from comment_utils.managers import CommentedObjectManager 94 95 class LiveEntryManager(CommentedObjectManager): 96 def get_query_set(self): 97 return super(LiveEntryManager, self).get_query_set().filter(status__exact=1) 98 99Then, ``LiveEntryManager`` could be attached to ``Entry`` in the same 100fashion as any other custom manager, and it would provide the 101``most_commented`` method in addition to performing the custom 102filtering (note that ``most_commented``, in this case, would only look 103at entries with "live" status, due to the overriding of 104``get_query_set`` in ``LiveEntryManager``).