PageRenderTime 158ms CodeModel.GetById 70ms app.highlight 2ms RepoModel.GetById 75ms app.codeStats 1ms

/docs/ref/contrib/comments/index.txt

https://code.google.com/p/mango-py/
Plain Text | 307 lines | 206 code | 101 blank | 0 comment | 0 complexity | 7c031adab9dbb84b2d66c07b33df47dc MD5 | raw file
  1===========================
  2Django's comments framework
  3===========================
  4
  5.. module:: django.contrib.comments
  6   :synopsis: Django's comment framework
  7
  8.. highlightlang:: html+django
  9
 10Django includes a simple, yet customizable comments framework. The built-in
 11comments framework can be used to attach comments to any model, so you can use
 12it for comments on blog entries, photos, book chapters, or anything else.
 13
 14.. note::
 15
 16    If you used to use Django's older (undocumented) comments framework, you'll
 17    need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>`
 18    for instructions.
 19
 20Quick start guide
 21=================
 22
 23To get started using the ``comments`` app, follow these steps:
 24
 25    #. Install the comments framework by adding ``'django.contrib.comments'`` to
 26       :setting:`INSTALLED_APPS`.
 27
 28    #. Run ``manage.py syncdb`` so that Django will create the comment tables.
 29
 30    #. Add the comment app's URLs to your project's ``urls.py``:
 31
 32       .. code-block:: python
 33
 34            urlpatterns = patterns('',
 35                ...
 36                (r'^comments/', include('django.contrib.comments.urls')),
 37                ...
 38            )
 39
 40    #. Use the `comment template tags`_ below to embed comments in your
 41       templates.
 42
 43You might also want to examine :doc:`/ref/contrib/comments/settings`.
 44
 45Comment template tags
 46=====================
 47
 48You'll primarily interact with the comment system through a series of template
 49tags that let you embed comments and generate forms for your users to post them.
 50
 51Like all custom template tag libraries, you'll need to :ref:`load the custom
 52tags <loading-custom-template-libraries>` before you can use them::
 53
 54    {% load comments %}
 55
 56Once loaded you can use the template tags below.
 57
 58Specifying which object comments are attached to
 59------------------------------------------------
 60
 61Django's comments are all "attached" to some parent object. This can be any
 62instance of a Django model. Each of the tags below gives you a couple of
 63different ways you can specify which object to attach to:
 64
 65    #. Refer to the object directly -- the more common method. Most of the
 66       time, you'll have some object in the template's context you want
 67       to attach the comment to; you can simply use that object.
 68
 69       For example, in a blog entry page that has a variable named ``entry``,
 70       you could use the following to load the number of comments::
 71
 72            {% get_comment_count for entry as comment_count %}.
 73
 74    #. Refer to the object by content-type and object id. You'd use this method
 75       if you, for some reason, don't actually have direct access to the object.
 76
 77       Following the above example, if you knew the object ID was ``14`` but
 78       didn't have access to the actual object, you could do something like::
 79
 80            {% get_comment_count for blog.entry 14 as comment_count %}
 81
 82       In the above, ``blog.entry`` is the app label and (lower-cased) model
 83       name of the model class.
 84
 85Displaying comments
 86-------------------
 87
 88To display a list of comments, you can use the template tags
 89:ttag:`render_comment_list` or :ttag:`get_comment_list`.
 90
 91.. templatetag:: render_comment_list
 92
 93Quickly rendering a comment list
 94~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 95
 96The easiest way to display a list of comments for some object is by using
 97:ttag:`render_comment_list`::
 98
 99    {% render_comment_list for [object] %}
100
101For example::
102
103    {% render_comment_list for event %}
104
105This will render comments using a template named ``comments/list.html``, a
106default version of which is included with Django.
107
108.. templatetag:: get_comment_list
109
110Rendering a custom comment list
111~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113To get the list of comments for some object, use :ttag:`get_comment_list`::
114
115    {% get_comment_list for [object] as [varname] %}
116
117For example::
118
119    {% get_comment_list for event as comment_list %}
120    {% for comment in comment_list %}
121        ...
122    {% endfor %}
123
124This returns a list of :class:`~django.contrib.comments.models.Comment` objects;
125see :doc:`the comment model documentation </ref/contrib/comments/models>` for
126details.
127
128.. templatetag:: get_comment_permalink
129
130Linking to comments
131-------------------
132
133.. versionadded:: 1.2
134
135To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`::
136
137    {% get_comment_permalink comment_obj [format_string] %}
138
139By default, the named anchor that will be appended to the URL will be the letter
140'c' followed by the comment id, for example 'c82'. You may specify a custom
141format string if you wish to override this behavior::
142
143    {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%}
144
145The format string is a standard python format string. Valid mapping keys
146include any attributes of the comment object.
147
148Regardless of whether you specify a custom anchor pattern, you must supply a
149matching named anchor at a suitable place in your template.
150
151For example::
152
153    {% for comment in comment_list %}
154        <a name="c{{ comment.id }}"></a>
155        <a href="{% get_comment_permalink comment %}">
156            permalink for comment #{{ forloop.counter }}
157        </a>
158        ...
159    {% endfor %}
160
161.. warning::
162
163    There's a known bug in Safari/Webkit which causes the named anchor to be
164    forgotten following a redirect. The practical impact for comments is that
165    the Safari/webkit browsers will arrive at the correct page but will not
166    scroll to the named anchor.
167
168.. templatetag:: get_comment_count
169
170Counting comments
171-----------------
172
173To count comments attached to an object, use :ttag:`get_comment_count`::
174
175    {% get_comment_count for [object] as [varname]  %}
176
177For example::
178
179        {% get_comment_count for event as comment_count %}
180
181        <p>This event has {{ comment_count }} comments.</p>
182
183
184Displaying the comment post form
185--------------------------------
186
187To show the form that users will use to post a comment, you can use
188:ttag:`render_comment_form` or :ttag:`get_comment_form`
189
190.. templatetag:: render_comment_form
191
192Quickly rendering the comment form
193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
195The easiest way to display a comment form is by using
196:ttag:`render_comment_form`::
197
198    {% render_comment_form for [object] %}
199
200For example::
201
202    {% render_comment_form for event %}
203
204This will render comments using a template named ``comments/form.html``, a
205default version of which is included with Django.
206
207.. templatetag:: get_comment_form
208
209Rendering a custom comment form
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211
212If you want more control over the look and feel of the comment form, you use use
213:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that
214you can use in the template::
215
216    {% get_comment_form for [object] as [varname] %}
217
218A complete form might look like::
219
220    {% get_comment_form for event as form %}
221    <table>
222      <form action="{% comment_form_target %}" method="post">
223        {% csrf_token %}
224        {{ form }}
225        <tr>
226          <td colspan="2">
227            <input type="submit" name="submit" value="Post">
228            <input type="submit" name="preview" value="Preview">
229          </td>
230        </tr>
231      </form>
232    </table>
233
234Be sure to read the `notes on the comment form`_, below, for some special
235considerations you'll need to make if you're using this approach.
236
237.. templatetag:: comment_form_target
238
239Getting the comment form target
240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241
242You may have noticed that the above example uses another template tag --
243:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
244form. This will always return the correct URL that comments should be posted to;
245you'll always want to use it like above::
246
247    <form action="{% comment_form_target %}" method="post">
248
249Redirecting after the comment post
250~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
251
252To specify the URL you want to redirect to after the comment has been posted,
253you can include a hidden form input called ``next`` in your comment form. For example::
254
255    <input type="hidden" name="next" value="{% url my_comment_was_posted %}" />
256
257.. _notes-on-the-comment-form:
258
259Notes on the comment form
260-------------------------
261
262The form used by the comment system has a few important anti-spam attributes you
263should know about:
264
265    * It contains a number of hidden fields that contain timestamps, information
266      about the object the comment should be attached to, and a "security hash"
267      used to validate this information. If someone tampers with this data --
268      something comment spammers will try -- the comment submission will fail.
269
270      If you're rendering a custom comment form, you'll need to make sure to
271      pass these values through unchanged.
272
273    * The timestamp is used to ensure that "reply attacks" can't continue very
274      long. Users who wait too long between requesting the form and posting a
275      comment will have their submissions refused.
276
277    * The comment form includes a "honeypot_" field. It's a trap: if any data is
278      entered in that field, the comment will be considered spam (spammers often
279      automatically fill in all fields in an attempt to make valid submissions).
280
281      The default form hides this field with a piece of CSS and further labels
282      it with a warning field; if you use the comment form with a custom
283      template you should be sure to do the same.
284
285The comments app also depends on the more general :doc:`Cross Site Request
286Forgery protection </ref/contrib/csrf>` that comes with Django.  As described in
287the documentation, it is best to use ``CsrfViewMiddleware``.  However, if you
288are not using that, you will need to use the ``csrf_protect`` decorator on any
289views that include the comment form, in order for those views to be able to
290output the CSRF token and cookie.
291
292.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
293
294More information
295================
296
297.. toctree::
298   :maxdepth: 1
299
300   models
301   settings
302   signals
303   upgrade
304   custom
305   forms
306   moderation
307   example