From 936c99b7c745a3e104d274f6e0dabb68e3086ca0 Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Mon, 4 Jan 2010 02:27:37 +0000 Subject: [PATCH] Fixed #9819 - Added exemplary documentation for comments app. Thanks for the initial patch, Thejaswi Puthraya. git-svn-id: http://code.djangoproject.com/svn/django/trunk@12079 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/comments/example.txt | 195 ++++++++++++++++++++++++++ docs/ref/contrib/comments/index.txt | 1 + 2 files changed, 196 insertions(+) create mode 100644 docs/ref/contrib/comments/example.txt diff --git a/docs/ref/contrib/comments/example.txt b/docs/ref/contrib/comments/example.txt new file mode 100644 index 0000000000..626e8b4a95 --- /dev/null +++ b/docs/ref/contrib/comments/example.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 `. + +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. + +Template +======== + +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 blog.post object_pk as comment_count %} +

{{ comment_count }} comments have been posted.

+ +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 %} +

{{ comment_count }} comments have been posted.

+ +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 blog.post object_pk as comment_list %} + {% for comment in comment_list %} +

Posted by: {{ comment.user_name }} on {{ comment.submit_date }}

+ ... +

Comment: {{ comment.comment }}

+ ... + {% 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 +`, :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 field.name "comment" %} + + ... + {% endfor %} + +But let's look at a simple example:: + + {% get_comment_form for entry as form %} + + + + {{ form }} + + + + + +
+ +Flagging +======== + +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/{{ +comment.id }}/``. 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``. + +Feeds +===== + +Suppose you want to export a :ref:`feed ` of the +latest comments, you can use the in-built :class:`LatestCommentFeed`. Just +enable it in your project's ``urls.py``: + +.. code-block:: python + + from django.conf.urls.defaults import * + from django.contrib.comments.feeds import LatestCommentFeed + + feeds = { + 'latest': LatestCommentFeed, + } + + urlpatterns = patterns('', + # ... + (r'^feeds/(?P.*)/$', 'django.contrib.syndication.views.feed', + {'feed_dict': feeds}), + # ... + ) + +Now you should have the latest comment feeds being served off ``/feeds/latest/``. + +Moderation +========== + +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 +`. 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/models.py``, 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``. diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 6ee109782f..54fb7a192d 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -238,3 +238,4 @@ More information custom forms moderation + example