← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal-security

« back to all changes in this revision

Viewing changes to docs/ref/contrib/comments/example.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2010-05-21 07:52:55 UTC
  • mfrom: (1.3.6 upstream)
  • mto: This revision was merged to the branch mainline in revision 28.
  • Revision ID: james.westby@ubuntu.com-20100521075255-ii78v1dyfmyu3uzx
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/comments/example.txt
 
1
.. _ref-contrib-comments-example:
 
2
 
 
3
.. highlightlang:: html+django
 
4
 
 
5
===========================================
 
6
Example of using the in-built comments app
 
7
===========================================
 
8
 
 
9
Follow the first three steps of the quick start guide in the
 
10
:ref:`documentation <ref-contrib-comments-index>`.
 
11
 
 
12
Now suppose, you have an app (``blog``) with a model (``Post``)
 
13
to which you want to attach comments. Let us also suppose that
 
14
you have a template called ``blog_detail.html`` where you want
 
15
to display the comments list and comment form.
 
16
 
 
17
Template
 
18
========
 
19
 
 
20
First, we should load the ``comment`` template tags in the
 
21
``blog_detail.html`` so that we can use it's functionality. So
 
22
just like all other custom template tag libraries::
 
23
 
 
24
    {% load comments %}
 
25
 
 
26
Next, let us add the number of comments attached to the particular
 
27
model instance of ``Post``. For this we assume that a context
 
28
variable ``object_pk`` is present which gives the ``id`` of the
 
29
instance of ``Post``.
 
30
 
 
31
The usage of the :ttag:`get_comment_count` tag is like below::
 
32
 
 
33
   {% get_comment_count for blog.post object_pk as comment_count %}
 
34
   <p>{{ comment_count }} comments have been posted.</p>
 
35
 
 
36
If you have the instance (say ``entry``) of the model (``Post``)
 
37
available in the context, then you can refer to it directly::
 
38
 
 
39
   {% get_comment_count for entry as comment_count %}
 
40
   <p>{{ comment_count }} comments have been posted.</p>
 
41
 
 
42
.. versionadded:: 1.2
 
43
 
 
44
Next, we can use the :ttag:`render_comment_list` tag, to render all comments
 
45
to the given instance (``entry``) by using the ``comments/list.html`` template.
 
46
 
 
47
   {% render_comment_list for entry %}
 
48
 
 
49
Django will will look for the ``list.html`` under the following directories
 
50
(for our example)::
 
51
 
 
52
  comments/blog/post/list.html
 
53
  comments/blog/list.html
 
54
  comments/list.html
 
55
 
 
56
To get a list of comments, we make use of the :ttag:`get_comment_list` tag.
 
57
This tag's usage is very similar to the :ttag:`get_comment_count` tag. We
 
58
need to remember that the :ttag:`get_comment_list` returns a list of comments
 
59
and hence we will have to iterate through them to display them::
 
60
 
 
61
   {% get_comment_list for blog.post object_pk as comment_list %}
 
62
   {% for comment in comment_list %}
 
63
   <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p>
 
64
   ...
 
65
   <p>Comment: {{ comment.comment }}</p>
 
66
   ...
 
67
   {% endfor %}
 
68
 
 
69
Finally, we display the comment form, enabling users to enter their
 
70
comments. There are two ways of doing so. The first is when you want to
 
71
display the comments template available under your ``comments/form.html``.
 
72
The other method gives you a chance to customize the form.
 
73
 
 
74
The first method makes use of the :ttag:`render_comment_form` tag. It's usage
 
75
too is similar to the other three tags we have discussed above::
 
76
 
 
77
   {% render_comment_form for entry %}
 
78
 
 
79
It looks for the ``form.html`` under the following directories
 
80
(for our example)::
 
81
 
 
82
   comments/blog/post/form.html
 
83
   comments/blog/form.html
 
84
   comments/form.html
 
85
 
 
86
Since we customize the form in the second method, we make use of another
 
87
tag called :ttag:`comment_form_target`. This tag on rendering gives the URL
 
88
where the comment form is posted. Without any :ref:`customization
 
89
<ref-contrib-comments-custom>`, :ttag:`comment_form_target` evaluates to
 
90
``/comments/post/``. We use this tag in the form's ``action`` attribute.
 
91
 
 
92
The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by
 
93
creating a context variable. One can iterate over the ``form`` object to
 
94
get individual fields. This gives you fine-grain control over the form::
 
95
 
 
96
  {% for field in form %}
 
97
  {% ifequal field.name "comment" %}
 
98
    <!-- Customize the "comment" field, say, make CSS changes -->
 
99
  ...
 
100
  {% endfor %}
 
101
 
 
102
But let's look at a simple example::
 
103
 
 
104
  {% get_comment_form for entry as form %}
 
105
  <!-- A context variable called form is created with the necessary hidden
 
106
  fields, timestamps and security hashes -->
 
107
  <table>
 
108
  <form action="{% comment_form_target %}" method="post">
 
109
    {{ form }}
 
110
    <tr>
 
111
      <td></td>
 
112
      <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
 
113
    </tr>
 
114
  </form>
 
115
  </table>
 
116
 
 
117
Flagging
 
118
========
 
119
 
 
120
If you want your users to be able to flag comments (say for profanity), you
 
121
can just direct them (by placing a link in your comment list) to ``/flag/{{
 
122
comment.id }}/``. Similarly, a user with requisite permissions (``"Can
 
123
moderate comments"``) can approve and delete comments. This can also be
 
124
done through the ``admin`` as you'll see later. You might also want to
 
125
customize the following templates:
 
126
 
 
127
  * ``flag.html``
 
128
  * ``flagged.html``
 
129
  * ``approve.html``
 
130
  * ``approved.html``
 
131
  * ``delete.html``
 
132
  * ``deleted.html``
 
133
 
 
134
found under the directory structure we saw for ``form.html``.
 
135
 
 
136
Feeds
 
137
=====
 
138
 
 
139
Suppose you want to export a :ref:`feed <ref-contrib-syndication>` of the
 
140
latest comments, you can use the in-built :class:`LatestCommentFeed`. Just
 
141
enable it in your project's ``urls.py``:
 
142
 
 
143
.. code-block:: python
 
144
 
 
145
  from django.conf.urls.defaults import *
 
146
  from django.contrib.comments.feeds import LatestCommentFeed
 
147
 
 
148
  feeds = {
 
149
      'latest': LatestCommentFeed,
 
150
  }
 
151
 
 
152
  urlpatterns = patterns('',
 
153
  # ...
 
154
      (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
 
155
          {'feed_dict': feeds}),
 
156
  # ...
 
157
  )
 
158
 
 
159
Now you should have the latest comment feeds being served off ``/feeds/latest/``.
 
160
 
 
161
Moderation
 
162
==========
 
163
 
 
164
Now that we have the comments framework working, we might want to have some
 
165
moderation setup to administer the comments. The comments framework comes
 
166
in-built with :ref:`generic comment moderation
 
167
<ref-contrib-comments-moderation>`. The comment moderation has the following
 
168
features (all of which or only certain can be enabled):
 
169
 
 
170
  * Enable comments for a particular model instance.
 
171
  * Close comments after a particular (user-defined) number of days.
 
172
  * Email new comments to the site-staff.
 
173
 
 
174
To enable comment moderation, we subclass the :class:`CommentModerator` and
 
175
register it with the moderation features we want. Let us suppose we want to
 
176
close comments after 7 days of posting and also send out an email to the
 
177
site staff. In ``blog/models.py``, we register a comment moderator in the
 
178
following way:
 
179
 
 
180
.. code-block:: python
 
181
 
 
182
   from django.contrib.comments.moderation import CommentModerator, moderator
 
183
   from django.db import models
 
184
   
 
185
   class Post(models.Model):
 
186
       title   = models.CharField(max_length = 255)
 
187
       content = models.TextField()
 
188
       posted_date = models.DateTimeField()
 
189
   
 
190
   class PostModerator(CommentModerator):
 
191
       email_notification = True
 
192
       auto_close_field   = 'posted_date'
 
193
       # Close the comments after 7 days.
 
194
       close_after        = 7
 
195
   
 
196
   moderator.register(Post, PostModerator)
 
197
 
 
198
The generic comment moderation also has the facility to remove comments.
 
199
These comments can then be moderated by any user who has access to the
 
200
``admin`` site and the ``Can moderate comments`` permission (can be set
 
201
under the ``Users`` page in the ``admin``).
 
202
 
 
203
The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the
 
204
``Action`` drop-down in the ``admin`` under the ``Comments`` page.
 
205
 
 
206
.. note::
 
207
 
 
208
     Only a super-user will be able to delete comments from the database.
 
209
     ``Remove Comments`` only sets the ``is_public`` attribute to
 
210
     ``False``.