Ticket #12871: comments2.diff

docs/ref/contrib/comments/index.txt

@@ -251 +251 @@
 
     <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 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 "item"::
+
+    {% if user.is_authenticated %}
+        {% get_comment_form for item 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 item_view item.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 {% csrf_token %} field accommodates the :ref:`Cross-Site Request Forgery Requirements
+< ref-contrib-csrf>` in Django 1.2. 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 :ref:`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 {
+        visibility:hidden;
+    }
+
+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