Refactored Django's comment system.

Much of this work was done by Thejaswi Puthraya as part of Google's Summer of Code project; much thanks to him for the work, and to them for the program.

This is a backwards-incompatible change; see the upgrading guide in docs/ref/contrib/comments/upgrade.txt for instructions if you were using the old comments system.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8557 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 313 insertions, 1 deletions

diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
new file mode 100644
index 0000000000..97e69d11cb
--- /dev/null
+++ b/docs/ref/contrib/comments/index.txt
@@ -0,0 +1,212 @@
+.. _ref-contrib-comments-index:
+
+===========================
+Django's comments framework
+===========================
+
+.. module:: django.contrib.comments
+   :synopsis: Django's comment framework
+
+Django includes a simple, yet customizable comments framework. The built-in
+comments framework can be used to attach comments to any model, so you can use
+it for comments on blog entries, photos, book chapters, or anything else.
+
+.. note::
+
+    If you used to use Django's older (undocumented) comments framework, you'll
+    need to upgrade. See the :ref:`upgrade guide <ref-contrib-comments-upgrade>`
+    for instructions.
+
+Quick start guide
+=================
+
+To get started using the ``comments`` app, follow these steps:
+
+    #. Install the comments framework by adding ``'django.contrib.comments'`` to    
+       :setting:`INSTALLED_APPS`.
+
+    #. Run ``manage.py syncdb`` so that Django will create the comment tables.
+
+    #. Add the comment app's URLs to your project's ``urls.py``:
+   
+       .. code-block:: python
+
+            urlpatterns = patterns('',
+                ...
+                (r'^comments/', include('django.contrib.comments.urls')),
+                ...
+            )
+
+    #. Use the `comment template tags`_ below to embed comments in your
+       templates.
+    
+You might also want to examine the :ref:`ref-contrib-comments-settings`
+    
+Comment template tags
+=====================
+
+You'll primarily interact with the comment system through a series of template
+tags that let you embed comments and generate forms for your users to post them.
+
+Like all custom template tag libraries, you'll need to :ref:`load the custom
+tags <loading-custom-template-libraries>` before you can use them::
+
+    {% load comments %}
+
+Once loaded you can use the template tags below.
+
+Specifying which object comments are attached to
+------------------------------------------------
+
+Django's comments are all "attached" to some parent object. This can be any
+instance of a Django model. Each of the tags below gives you a couple of
+different ways you can specify which object to attach to:
+
+    #. Refer to the object directly -- the more common method. Most of the
+       time, you'll have some object in the template's context you want
+       to attach the comment to; you can simply use that object.
+       
+       For example, in a blog entry page that has a variable named ``entry``, 
+       you could use the following to load the number of comments::
+       
+            {% get_comment_count for entry as comment_count %}.
+            
+    #. Refer to the object by content-type and object id. You'd use this method
+       if you, for some reason, don't actually have direct access to the object.
+       
+       Following the above example, if you knew the object ID was ``14`` but
+       didn't have access to the actual object, you could do something like::
+       
+            {% get_comment_count for blog.entry 14 as comment_count %}
+            
+       In the above, ``blog.entry`` is the app label and (lower-cased) model
+       name of the model class.
+
+.. templatetag:: get_comment_list
+
+Displaying comments
+-------------------
+
+To get a the list of comments for some object, use :ttag:`get_comment_list`::
+
+    {% get_comment_list for [object] as [varname] %}
+
+For example::
+
+    {% get_comment_list for event as comment_list %}
+    {% for comment in comment_list %}
+        ...
+    {% endfor %}
+
+.. templatetag:: get_comment_count
+
+Counting comments
+-----------------
+
+To count comments attached to an object, use :ttag:`get_comment_count`::
+
+    {% get_comment_count for [object] as [varname]  %}
+
+For example::
+
+        {% get_comment_count for event as comment_count %}
+        
+        <p>This event has {{ comment_count }} comments.</p>
+        
+
+Displaying the comment post form
+--------------------------------
+
+To show the form that users will use to post a comment, you can use
+:ttag:`render_comment_form` or :ttag:`get_comment_form`
+
+.. templatetag:: render_comment_form
+
+Quickly rendering the comment form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way to display a comment form is by using
+:ttag:`render_comment_form`::
+
+    {% render_comment_form for [object] %}
+
+For example::
+
+    {% render_comment_form for event %}
+
+This will render comments using a template named ``comments/form.html``, a
+default version of which is included with Django.
+
+.. templatetag:: get_comment_form
+
+Rendering a custom comment form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want more control over the look and feel of the comment form, you use use
+:ttag:`get_comment_form` to get a :ref:`form object <topics-forms-index>` that
+you can use in the template::
+
+    {% get_comment_form for [object] %}
+    
+A complete form might look like::
+
+    {% get_comment_form for event %}
+    <form action="{% comment_form_target %}" method="POST">
+      {{ form }}
+      <p class="submit">
+        <input type="submit" name="submit" class="submit-post" value="Preview">
+      </p>
+    </form>
+    
+Be sure to read the `notes on the comment form`_, below, for some special
+considerations you'll need to make if you're using this aproach.
+
+.. templatetag:: comment_form_target
+
+Getting the comment form target
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may have noticed that the above example uses another template tag --
+:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
+form. This will always return the correct URL that comments should be posted to;
+you'll always want to use it like above::
+
+    <form action="{% comment_form_target %}" method="POST">
+
+Notes on the comment form
+-------------------------
+
+The form used by the comment system has a few important anti-spam attributes you
+should know about:
+
+    * It contains a number of hidden fields that contain timestamps, information
+      about the object the comment should be attached to, and a "security hash"
+      used to validate this information. If someone tampers with this data -- 
+      something comment spammers will try -- the comment submission will fail.
+      
+      If you're rendering a custom comment form, you'll need to make sure to
+      pass these values through unchanged.
+      
+    * The timestamp is used to ensure that "reply attacks" can't continue very
+      long. Users who wait too long between requesting the form and posting a
+      comment will have their submissions refused.
+      
+    * The comment form includes a "honeypot_" field. It's a trap: if any data is
+      entered in that field, the comment will be considered spam (spammers often
+      automatically fill in all fields in an attempt to make valid submissions).
+      
+      The default form hides this field with a piece of CSS and further labels
+      it with a warning field; if you use the comment form with a custom
+      template you should be sure to do the same.
+    
+.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
+
+More information
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   settings
+   upgrade
+
diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt
new file mode 100644
index 0000000000..4bd60f7bcb
--- /dev/null
+++ b/docs/ref/contrib/comments/settings.txt
@@ -0,0 +1,34 @@
+.. _ref-contrib-comments-settings:
+
+================
+Comment settings
+================
+
+These settings configure the behavior of the comments framework:
+
+.. setting:: COMMENTS_HIDE_REMOVED
+
+COMMENTS_HIDE_REMOVED
+---------------------
+
+If ``True`` (default), removed comments will be excluded from comment
+lists/counts (as taken from template tags). Otherwise, the template author is
+responsible for some sort of a "this comment has been removed by the site staff"
+message.
+
+.. setting:: COMMENT_MAX_LENGTH
+
+COMMENT_MAX_LENGTH
+------------------
+
+The maximum length of the comment field, in characters. Comments longer than
+this will be rejected. Defaults to 3000.
+
+.. setting:: COMENTS_APP
+
+COMENTS_APP
+-----------
+
+The app (i.e. entry in ``INSTALLED_APPS``) responsible for all "business logic."
+You can change this to provide custom comment models and forms, though this is
+currently undocumented.
diff --git a/docs/ref/contrib/comments/upgrade.txt b/docs/ref/contrib/comments/upgrade.txt
new file mode 100644
index 0000000000..0f0b67f219
--- /dev/null
+++ b/docs/ref/contrib/comments/upgrade.txt
@@ -0,0 +1,63 @@
+.. _ref-contrib-comments-upgrade:
+
+===============================================
+Upgrading from Django's previous comment system
+===============================================
+
+Prior versions of Django included an outdated, undocumented comment system. Users who reverse-engineered this framework will need to upgrade to use the
+new comment system; this guide explains how.
+
+The main changes from the old system are:
+
+    * This new system is documented.
+    
+    * It uses modern Django features like :ref:`forms <topics-forms-index>` and
+      :ref:`modelforms <topics-forms-modelforms>`.
+
+    * It has a single ``Comment`` model instead of separate ``FreeComment`` and
+      ``Comment`` models.
+
+    * Comments have "email" and "URL" fields.
+
+    * No ratings, photos and karma. This should only effect World Online.
+
+    * The ``{% comment_form %}`` tag no longer exists. Instead, there's now two
+      functions: ``{% get_comment_form %}``, which returns a form for posting a
+      new comment, and ``{% render_comment_form %}``, which renders said form
+      using the ``comments/form.html`` template.
+
+Upgrading data
+--------------
+
+The data models have changed, as have the table names. To transfer your data into the new system, you'll need to directly run the following SQL:
+
+.. code-block:: sql
+
+    BEGIN;
+
+    INSERT INTO django_comments 
+        (content_type_id, object_pk, site_id, user_name, user_email, user_url,
+        comment, submit_date, ip_address, is_public, is_removed)
+    SELECT
+        content_type_id, object_id, site_id, person_name, '', '', comment,
+        submit_date, ip_address, is_public, approved
+    FROM comments_freecomment;
+
+    INSERT INTO django_comments 
+        (content_type_id, object_pk, site_id, user_id, comment, submit_date,
+        ip_address, is_public, is_removed) 
+    SELECT 
+        content_type_id, object_id, site_id, user_id, comment, submit_date,
+        ip_address, is_public, is_removed
+    FROM comments_comment;
+
+    UPDATE django_comments SET user_name = (
+        SELECT username FROM auth_user 
+        WHERE django_comments.user_id = auth_user.id
+    );
+    UPDATE django_comments SET user_email = (
+        SELECT email FROM auth_user 
+        WHERE django_comments.user_id = auth_user.id
+    );
+    
+    COMMIT;
diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt
index e6c693d905..2f3075ba04 100644
--- a/docs/ref/contrib/index.txt
+++ b/docs/ref/contrib/index.txt
@@ -26,6 +26,7 @@ those packages have.
 
    admin
    auth
+   comments/index
    contenttypes
    csrf
    databrowse
@@ -58,7 +59,9 @@ See :ref:`topics-auth`.
 comments
 ========
 
-A simple yet flexible comments system. This is not yet documented.
+**New in Django development version.**
+
+A simple yet flexible comments system. See :ref:`ref-contrib-comments-index`.
 
 contenttypes
 ============