/docs/managers.txt

  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``).