Django Comments framework

I am writing this mainly for personal use and future reference, so
please excuse any lack of order or clarity. I will do my best to avoid
those.

The Comments framework is probably one of the least documented parts of
Django, but one with evident utility. It is made of two subparts, the
FreeComments and Comments part. For the first you can find good
references here and here.
But nothing for the Comment part.

I’ve decided to try to understand the framework by
reading the code and looking at the Lost-Theories code.

There seems to be three concepts in the Comments framework:

• The karma concept, largely used at slashdot,
  where each comment can be given or taken out points of karma. Once a
  comment is under a certain treshold, it is not displayed anymore. Update: I actually got the concept of karma wrong. Slashdot gives karma to his users, while django gives karma to the comments themselves.
• Each comment allows a User to rate up to 8 different characteristics.
  This is the meaning of the eight ratingI = models.PositiveSmallIntegerField(_(‘rating #I’), blank=True, null=True) you find on the Comment model.
  That way, a comment of a book could rate the beauty, the style, how interesting the book is,…
• Each Comment can be flagged once by each user. This could be used to highlight interesting
  comments, offensive comments,…

Besides that, there seems to be automatic ways of creation and deletion of comments, flagging, voting,…

The Karma functions:

There are views that will automagically change the karma of each comment. Those are located in django/contrib/comments/views/karma.py and will use the urls.py in django/contrib/comments/urls/comments.py.

It seems that you simply have to define the comments/karma_vote_accepted.html template. In the context of this template you find the following variables:

• comment: The comments.comments being rated.

In order to add/take out karma points you will have to add karma/vote/(?P<comment_id>\d+)/(?P<vote>up|down)/
links to the comments. In the
comments object there’s a get_karma_total() that will allow you to
display the total karma.

The Rating functions:

Everybody love to rate. Books, recipes, songs… Django Comments allows us to rate up to 8 different characteristics.

Those
characteristics are not defined anywhere. They are part of the Comment
object. They can be accessed from the working model as follows (example
from Lost-Theories, Episode model in lost-episodes):

 def get_rating1(self):
        from django.contrib.contenttypes.models import ContentType
        from django.contrib.comments.models import Comment
        ctype = ContentType.objects.get(name='episode')
        comments = Comment.objects.filter(content_type=ctype.id, object_id=self.id)
        rating_list = []
        rating_total = 0
        for comment in comments:
            if comment.rating1:
                if comment.valid_rating:
                    rating_list.append(comment.rating1)
                    rating_total += comment.rating1
        if rating_total != 0:
            avg = rating_total / len(rating_list)
            return avg
        else:
            return 0

    def get_num_rating1(self):
        from django.contrib.contenttypes.models import ContentType
        from django.contrib.comments.models import Comment
        ctype = ContentType.objects.get(name='episode')
        comments = Comment.objects.filter(content_type=ctype.id, object_id=self.id)
        rating_list = []
        rating_total = 0
        for comment in comments:
            if comment.rating1:
                if comment.valid_rating:
                    rating_list.append(comment.rating1)
                    rating_total += comment.rating1
        num_ratings = len(rating_list)
        return num_ratings

In order to use this feature in the templates, the following lines are included:

{% comment_form for lost_episodes.episode episode.id with ratings_optional scale:1-5|Rating %}

This
is used to display the comment form, and means that we are using the
model from lost_episodes.episode, using the id field of episode, and
that the rating (with name “Rating” is optional. The rate, if used,
will be between 1 and 5.

The Flag functions:

As said before, it is sometimes interesting to flag comments, either due to their offensive content, their interest or their originality. Django provides (oh! surprise! ) a nice interface to this feature.

Update: Afte checking the API stability page I’ve seen that the comment framework will probably suffer a complete rewrite before Django 1.0. So I am not sure I will go further on this direction.