Django includes a simple, yet customizable comments framework. The built-in comments framework can be used to attach comments to any model, so you can use it for comments on blog entries, photos, book chapters, or anything else.
Note
If you used to use Django’s older (undocumented) comments framework, you’ll need to upgrade. See the upgrade guide for instructions.
To get started using the comments app, follow these steps:
Install the comments framework by adding 'django.contrib.comments' to INSTALLED_APPS.
Run manage.py syncdb so that Django will create the comment tables.
Add the comment app’s URLs to your project’s urls.py:
urlpatterns = patterns('',
...
(r'^comments/', include('django.contrib.comments.urls')),
...
)
Use the comment template tags below to embed comments in your templates.
You might also want to examine Comment settings.
You'll primarily interact with the comment system through a series of template tags that let you embed comments and generate forms for your users to post them.
Like all custom template tag libraries, you'll need to load the custom tags before you can use them:
{% load comments %}
Once loaded you can use the template tags below.
Django's comments are all "attached" to some parent object. This can be any instance of a Django model. Each of the tags below gives you a couple of different ways you can specify which object to attach to:
Refer to the object directly -- the more common method. Most of the time, you'll have some object in the template's context you want to attach the comment to; you can simply use that object.
For example, in a blog entry page that has a variable named entry, you could use the following to load the number of comments:
{% get_comment_count for entry as comment_count %}.
Refer to the object by content-type and object id. You'd use this method if you, for some reason, don't actually have direct access to the object.
Following the above example, if you knew the object ID was 14 but didn't have access to the actual object, you could do something like:
{% get_comment_count for blog.entry 14 as comment_count %}
In the above, blog.entry is the app label and (lower-cased) model name of the model class.
To get a the list of comments for some object, use get_comment_list:
{% get_comment_list for [object] as [varname] %}
For example:
{% get_comment_list for event as comment_list %}
{% for comment in comment_list %}
...
{% endfor %}
This returns a list of Comment objects; see the comment model documentation for details.
To count comments attached to an object, use get_comment_count:
{% get_comment_count for [object] as [varname] %}
For example:
{% get_comment_count for event as comment_count %}
<p>This event has {{ comment_count }} comments.</p>
To show the form that users will use to post a comment, you can use render_comment_form or get_comment_form
The easiest way to display a comment form is by using render_comment_form:
{% render_comment_form for [object] %}
For example:
{% render_comment_form for event %}
This will render comments using a template named comments/form.html, a default version of which is included with Django.
If you want more control over the look and feel of the comment form, you use use get_comment_form to get a form object that you can use in the template:
{% get_comment_form for [object] as [varname] %}
A complete form might look like:
{% get_comment_form for event as form %}
<form action="{% comment_form_target %}" method="POST">
{{ form }}
<tr>
<td></td>
<td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
</tr>
</form>
Be sure to read the notes on the comment form, below, for some special considerations you'll need to make if you're using this approach.
You may have noticed that the above example uses another template tag -- comment_form_target -- to actually get the action attribute of the form. This will always return the correct URL that comments should be posted to; you'll always want to use it like above:
<form action="{% comment_form_target %}" method="POST">
To specify the URL you want to redirect to after the comment has been posted, you can include a hidden form input called next in your comment form. For example:
<input type="hidden" name="next" value="{% url my_comment_was_posted %}" />
The form used by the comment system has a few important anti-spam attributes you should know about:
It contains a number of hidden fields that contain timestamps, information about the object the comment should be attached to, and a "security hash" used to validate this information. If someone tampers with this data -- something comment spammers will try -- the comment submission will fail.
If you're rendering a custom comment form, you'll need to make sure to pass these values through unchanged.
The timestamp is used to ensure that "reply attacks" can't continue very long. Users who wait too long between requesting the form and posting a comment will have their submissions refused.
The comment form includes a "honeypot" field. It's a trap: if any data is entered in that field, the comment will be considered spam (spammers often automatically fill in all fields in an attempt to make valid submissions).
The default form hides this field with a piece of CSS and further labels it with a warning field; if you use the comment form with a custom template you should be sure to do the same.
Sep 20, 2009