Browse files

[1.1.X] Fixed #9819 - Added exemplary documentation for comments app.…

… Thanks for the initial patch, Thejaswi Puthraya.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent d060d84 commit b3ec5e68eb5f9675d6e7e89dc8e771b9147dc74f @jezdez jezdez committed Jan 17, 2010
Showing with 196 additions and 0 deletions.
  1. +195 −0 docs/ref/contrib/comments/example.txt
  2. +1 −0 docs/ref/contrib/comments/index.txt
@@ -0,0 +1,195 @@
+.. _ref-contrib-comments-example:
+.. highlightlang:: html+django
+Example of using the in-built comments app
+Follow the first three steps of the quick start guide in the
+:ref:`documentation <ref-contrib-comments-index>`.
+Now suppose, you have an app (``blog``) with a model (``Post``)
+to which you want to attach comments. Let us also suppose that
+you have a template called ``blog_detail.html`` where you want
+to display the comments list and comment form.
+First, we should load the ``comment`` template tags in the
+``blog_detail.html`` so that we can use it's functionality. So
+just like all other custom template tag libraries::
+ {% load comments %}
+Next, let us add the number of comments attached to the particular
+model instance of ``Post``. For this we assume that a context
+variable ``object_pk`` is present which gives the ``id`` of the
+instance of ``Post``.
+The usage of the :ttag:`get_comment_count` tag is like below::
+ {% get_comment_count for object_pk as comment_count %}
+ <p>{{ comment_count }} comments have been posted.</p>
+If you have the instance (say ``entry``) of the model (``Post``)
+available in the context, then you can refer to it directly::
+ {% get_comment_count for entry as comment_count %}
+ <p>{{ comment_count }} comments have been posted.</p>
+To get a list of comments, we make use of the :ttag:`get_comment_list` tag.
+This tag's usage is very similar to the :ttag:`get_comment_count` tag. We
+need to remember that the :ttag:`get_comment_list` returns a list of comments
+and hence we will have to iterate through them to display them::
+ {% get_comment_list for object_pk as comment_list %}
+ {% for comment in comment_list %}
+ <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p>
+ ...
+ <p>Comment: {{ comment.comment }}</p>
+ ...
+ {% endfor %}
+Finally, we display the comment form, enabling users to enter their
+comments. There are two ways of doing so. The first is when you want to
+display the comments template available under your ``comments/form.html``.
+The other method gives you a chance to customize the form.
+The first method makes use of the :ttag:`render_comment_form` tag. It's usage
+too is similar to the other two tags we have discussed above::
+ {% render_comment_form for entry %}
+It looks for the ``form.html`` under the following directories
+(for our example)::
+ comments/blog/post/form.html
+ comments/blog/form.html
+ comments/form.html
+Since we customize the form in the second method, we make use of another
+tag called :ttag:`comment_form_target`. This tag on rendering gives the URL
+where the comment form is posted. Without any :ref:`customization
+<ref-contrib-comments-custom>`, :ttag:`comment_form_target` evaluates to
+``/comments/post/``. We use this tag in the form's ``action`` attribute.
+The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by
+creating a context variable. One can iterate over the ``form`` object to
+get individual fields. This gives you fine-grain control over the form::
+ {% for field in form %}
+ {% ifequal "comment" %}
+ <!-- Customize the "comment" field, say, make CSS changes -->
+ ...
+ {% endfor %}
+But let's look at a simple example::
+ {% get_comment_form for entry as form %}
+ <!-- A context variable called form is created with the necessary hidden
+ fields, timestamps and security hashes -->
+ <table>
+ <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>
+ </table>
+If you want your users to be able to flag comments (say for profanity), you
+can just direct them (by placing a link in your comment list) to ``/flag/{{ }}/``. Similarly, a user with requisite permissions (``"Can
+moderate comments"``) can approve and delete comments. This can also be
+done through the ``admin`` as you'll see later. You might also want to
+customize the following templates:
+ * ``flag.html``
+ * ``flagged.html``
+ * ``approve.html``
+ * ``approved.html``
+ * ``delete.html``
+ * ``deleted.html``
+found under the directory structure we saw for ``form.html``.
+Suppose you want to export a :ref:`feed <ref-contrib-syndication>` of the
+latest comments, you can use the in-built :class:`LatestCommentFeed`. Just
+enable it in your project's ````:
+.. code-block:: python
+ from django.conf.urls.defaults import *
+ from django.contrib.comments.feeds import LatestCommentFeed
+ feeds = {
+ 'latest': LatestCommentFeed,
+ }
+ urlpatterns = patterns('',
+ # ...
+ (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+ {'feed_dict': feeds}),
+ # ...
+ )
+Now you should have the latest comment feeds being served off ``/feeds/latest/``.
+Now that we have the comments framework working, we might want to have some
+moderation setup to administer the comments. The comments framework comes
+in-built with :ref:`generic comment moderation
+<ref-contrib-comments-moderation>`. The comment moderation has the following
+features (all of which or only certain can be enabled):
+ * Enable comments for a particular model instance.
+ * Close comments after a particular (user-defined) number of days.
+ * Email new comments to the site-staff.
+To enable comment moderation, we subclass the :class:`CommentModerator` and
+register it with the moderation features we want. Let us suppose we want to
+close comments after 7 days of posting and also send out an email to the
+site staff. In ``blog/``, we register a comment moderator in the
+following way:
+.. code-block:: python
+ from django.contrib.comments.moderation import CommentModerator, moderator
+ from django.db import models
+ class Post(models.Model):
+ title = models.CharField(max_length = 255)
+ content = models.TextField()
+ posted_date = models.DateTimeField()
+ class PostModerator(CommentModerator):
+ email_notification = True
+ auto_close_field = 'posted_date'
+ # Close the comments after 7 days.
+ close_after = 7
+ moderator.register(Post, PostModerator)
+The generic comment moderation also has the facility to remove comments.
+These comments can then be moderated by any user who has access to the
+``admin`` site and the ``Can moderate comments`` permission (can be set
+under the ``Users`` page in the ``admin``).
+The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the
+``Action`` drop-down in the ``admin`` under the ``Comments`` page.
+.. note::
+ Only a super-user will be able to delete comments from the database.
+ ``Remove Comments`` only sets the ``is_public`` attribute to
+ ``False``.
@@ -231,3 +231,4 @@ More information
+ example

0 comments on commit b3ec5e6

Please sign in to comment.