PageRenderTime 253ms CodeModel.GetById 59ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/ref/contrib/comments/example.txt

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