From fea0ca4334b8c35100c0ca1048f81b9b3573bc26 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Fri, 28 Sep 2012 09:50:02 -0400
Subject: [PATCH] Fixed #12871 - Documented creation of a comment form for
 authenticated users; thanks shacker for patch.

---
 docs/ref/contrib/comments/index.txt | 50 +++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index 4b1dd96280..1c6ff7c7ed 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -254,6 +254,56 @@ you can include a hidden form input called ``next`` in your comment form. For ex
 
     <input type="hidden" name="next" value="{% url 'my_comment_was_posted' %}" />
 
+Providing a comment form for authenticated users
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a user is already authenticated, it makes little sense to display the name,
+email, and URL fields, since these can already be retrieved from their login
+data and profile. In addition, some sites will only accept comments from
+authenticated users.
+
+To provide a comment form for authenticated users, you can manually provide the
+additional fields expected by the Django comments framework. For example,
+assuming comments are attached to the model "object"::
+
+    {% if user.is_authenticated %}
+        {% get_comment_form for object as form %}
+        <form action="{% comment_form_target %}" method="POST">
+        {% csrf_token %}
+        {{ form.comment }}
+        {{ form.honeypot }}
+        {{ form.content_type }}
+        {{ form.object_pk }}
+        {{ form.timestamp }}
+        {{ form.security_hash }}
+        <input type="hidden" name="next" value="{% url 'object_detail_view' object.id %}" />
+        <input type="submit" value="Add comment" id="id_submit" />
+        </form>
+    {% else %}
+        <p>Please <a href="{% url 'auth_login' %}">log in</a> to leave a comment.</p>
+    {% endif %}
+
+The honeypot, content_type, object_pk, timestamp, and security_hash fields are
+fields that would have been created automatically if you had simply used
+``{{ form }}`` in your template, and are referred to in `Notes on the comment
+form`_ below.
+
+Note that we do not need to specify the user to be associated with comments
+submitted by authenticated users. This is possible because the :doc:`Built-in
+Comment Models</ref/contrib/comments/models>` that come with Django associate
+comments with authenticated users by default.
+
+In this example, the honeypot field will still be visible to the user; you'll
+need to hide that field in your CSS::
+
+    #id_honeypot {
+        display: none;
+    }
+
+If you want to accept either anonymous or authenticated comments, replace the
+contents of the "else" clause above with a standard comment form and the right
+thing will happen whether a user is logged in or not.
+
 .. _notes-on-the-comment-form:
 
 Notes on the comment form