Ticket #9268: comments_doc.diff

File comments_doc.diff, 15.6 KB (added by stuartk, 16 years ago)

Changes to comments documentation at docs/ref/contrib/comments/index.txt

  • ref/contrib/comments/index.txt

     
    1 .. _ref-contrib-comments-index:
    2 
    3 ===========================
    4 Django's comments framework
    5 ===========================
    6 
    7 .. module:: django.contrib.comments
    8    :synopsis: Django's comment framework
    9 
    10 .. highlightlang:: html+django
    11 
    12 Django includes a simple, yet customizable comments framework. The built-in
    13 comments framework can be used to attach comments to any model, so you can use
    14 it for comments on blog entries, photos, book chapters, or anything else.
    15 
    16 .. note::
    17 
    18     If you used to use Django's older (undocumented) comments framework, you'll
    19     need to upgrade. See the :ref:`upgrade guide <ref-contrib-comments-upgrade>`
    20     for instructions.
    21 
    22 Quick start guide
    23 =================
    24 
    25 To get started using the ``comments`` app, follow these steps:
    26 
    27     #. Install the comments framework by adding ``'django.contrib.comments'`` to   
    28        :setting:`INSTALLED_APPS`.
    29 
    30     #. Run ``manage.py syncdb`` so that Django will create the comment tables.
    31 
    32     #. Add the comment app's URLs to your project's ``urls.py``:
    33    
    34        .. code-block:: python
    35 
    36             urlpatterns = patterns('',
    37                 ...
    38                 (r'^comments/', include('django.contrib.comments.urls')),
    39                 ...
    40             )
    41 
    42     #. Use the `comment template tags`_ below to embed comments in your
    43        templates.
    44    
    45 You might also want to examine the :ref:`ref-contrib-comments-settings`
    46    
    47 Comment template tags
    48 =====================
    49 
    50 You'll primarily interact with the comment system through a series of template
    51 tags that let you embed comments and generate forms for your users to post them.
    52 
    53 Like all custom template tag libraries, you'll need to :ref:`load the custom
    54 tags <loading-custom-template-libraries>` before you can use them::
    55 
    56     {% load comments %}
    57 
    58 Once loaded you can use the template tags below.
    59 
    60 Specifying which object comments are attached to
    61 ------------------------------------------------
    62 
    63 Django's comments are all "attached" to some parent object. This can be any
    64 instance of a Django model. Each of the tags below gives you a couple of
    65 different ways you can specify which object to attach to:
    66 
    67     #. Refer to the object directly -- the more common method. Most of the
    68        time, you'll have some object in the template's context you want
    69        to attach the comment to; you can simply use that object.
    70        
    71        For example, in a blog entry page that has a variable named ``entry``,
    72        you could use the following to load the number of comments::
    73        
    74             {% get_comment_count for entry as comment_count %}.
    75            
    76     #. Refer to the object by content-type and object id. You'd use this method
    77        if you, for some reason, don't actually have direct access to the object.
    78        
    79        Following the above example, if you knew the object ID was ``14`` but
    80        didn't have access to the actual object, you could do something like::
    81        
    82             {% get_comment_count for blog.entry 14 as comment_count %}
    83            
    84        In the above, ``blog.entry`` is the app label and (lower-cased) model
    85        name of the model class.
    86 
    87 .. templatetag:: get_comment_list
    88 
    89 Displaying comments
    90 -------------------
    91 
    92 To get a the list of comments for some object, use :ttag:`get_comment_list`::
    93 
    94     {% get_comment_list for [object] as [varname] %}
    95 
    96 For example::
    97 
    98     {% get_comment_list for event as comment_list %}
    99     {% for comment in comment_list %}
    100         ...
    101     {% endfor %}
    102 
    103 .. templatetag:: get_comment_count
    104 
    105 Counting comments
    106 -----------------
    107 
    108 To count comments attached to an object, use :ttag:`get_comment_count`::
    109 
    110     {% get_comment_count for [object] as [varname]  %}
    111 
    112 For example::
    113 
    114         {% get_comment_count for event as comment_count %}
    115        
    116         <p>This event has {{ comment_count }} comments.</p>
    117        
    118 
    119 Displaying the comment post form
    120 --------------------------------
    121 
    122 To show the form that users will use to post a comment, you can use
    123 :ttag:`render_comment_form` or :ttag:`get_comment_form`
    124 
    125 .. templatetag:: render_comment_form
    126 
    127 Quickly rendering the comment form
    128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    129 
    130 The easiest way to display a comment form is by using
    131 :ttag:`render_comment_form`::
    132 
    133     {% render_comment_form for [object] %}
    134 
    135 For example::
    136 
    137     {% render_comment_form for event %}
    138 
    139 This will render comments using a template named ``comments/form.html``, a
    140 default version of which is included with Django.
    141 
    142 .. templatetag:: get_comment_form
    143 
    144 Rendering a custom comment form
    145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    146 
    147 If you want more control over the look and feel of the comment form, you use use
    148 :ttag:`get_comment_form` to get a :ref:`form object <topics-forms-index>` that
    149 you can use in the template::
    150 
    151     {% get_comment_form for [object] as [varname] %}
    152    
    153 A complete form might look like::
    154 
    155     {% get_comment_form for event as form %}
    156     <form action="{% comment_form_target %}" method="POST">
    157       {{ form }}
    158       <p class="submit">
    159         <input type="submit" name="preview" class="submit-post" value="Preview">
    160       </p>
    161     </form>
    162    
    163 Be sure to read the `notes on the comment form`_, below, for some special
    164 considerations you'll need to make if you're using this aproach.
    165 
    166 .. templatetag:: comment_form_target
    167 
    168 Getting the comment form target
    169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    170 
    171 You may have noticed that the above example uses another template tag --
    172 :ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
    173 form. This will always return the correct URL that comments should be posted to;
    174 you'll always want to use it like above::
    175 
    176     <form action="{% comment_form_target %}" method="POST">
    177 
    178 Notes on the comment form
    179 -------------------------
    180 
    181 The form used by the comment system has a few important anti-spam attributes you
    182 should know about:
    183 
    184     * It contains a number of hidden fields that contain timestamps, information
    185       about the object the comment should be attached to, and a "security hash"
    186       used to validate this information. If someone tampers with this data --
    187       something comment spammers will try -- the comment submission will fail.
    188      
    189       If you're rendering a custom comment form, you'll need to make sure to
    190       pass these values through unchanged.
    191      
    192     * The timestamp is used to ensure that "reply attacks" can't continue very
    193       long. Users who wait too long between requesting the form and posting a
    194       comment will have their submissions refused.
    195      
    196     * The comment form includes a "honeypot_" field. It's a trap: if any data is
    197       entered in that field, the comment will be considered spam (spammers often
    198       automatically fill in all fields in an attempt to make valid submissions).
    199      
    200       The default form hides this field with a piece of CSS and further labels
    201       it with a warning field; if you use the comment form with a custom
    202       template you should be sure to do the same.
    203    
    204 .. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
    205 
    206 More information
    207 ================
    208 
    209 .. toctree::
    210    :maxdepth: 1
    211 
    212    settings
    213    signals
    214    upgrade
    215 
     1.. _ref-contrib-comments-index:
     2
     3===========================
     4Django's comments framework
     5===========================
     6
     7.. module:: django.contrib.comments
     8   :synopsis: Django's comment framework
     9
     10.. highlightlang:: html+django
     11
     12Django includes a simple, yet customizable comments framework. The built-in
     13comments framework can be used to attach comments to any model, so you can use
     14it for comments on blog entries, photos, book chapters, or anything else.
     15
     16.. note::
     17
     18    If you used to use Django's older (undocumented) comments framework, you'll
     19    need to upgrade. See the :ref:`upgrade guide <ref-contrib-comments-upgrade>`
     20    for instructions.
     21
     22Quick start guide
     23=================
     24
     25To get started using the ``comments`` app, follow these steps:
     26
     27    #. Install the comments framework by adding ``'django.contrib.comments'`` to   
     28       :setting:`INSTALLED_APPS`.
     29
     30    #. Run ``manage.py syncdb`` so that Django will create the comment tables.
     31
     32    #. Add the comment app's URLs to your project's ``urls.py``:
     33   
     34       .. code-block:: python
     35
     36            urlpatterns = patterns('',
     37                ...
     38                (r'^comments/', include('django.contrib.comments.urls')),
     39                ...
     40            )
     41
     42    #. Use the `comment template tags`_ below to embed comments in your
     43       templates.
     44   
     45You might also want to examine the :ref:`ref-contrib-comments-settings`
     46   
     47Comment template tags
     48=====================
     49
     50You'll primarily interact with the comment system through a series of template
     51tags that let you embed comments and generate forms for your users to post them.
     52
     53Like all custom template tag libraries, you'll need to :ref:`load the custom
     54tags <loading-custom-template-libraries>` before you can use them::
     55
     56    {% load comments %}
     57
     58Once loaded you can use the template tags below.
     59
     60Specifying which object comments are attached to
     61------------------------------------------------
     62
     63Django's comments are all "attached" to some parent object. This can be any
     64instance of a Django model. Each of the tags below gives you a couple of
     65different ways you can specify which object to attach to:
     66
     67    #. Refer to the object directly -- the more common method. Most of the
     68       time, you'll have some object in the template's context you want
     69       to attach the comment to; you can simply use that object.
     70       
     71       For example, in a blog entry page that has a variable named ``entry``,
     72       you could use the following to load the number of comments::
     73       
     74            {% get_comment_count for entry as comment_count %}.
     75           
     76    #. Refer to the object by content-type and object id. You'd use this method
     77       if you, for some reason, don't actually have direct access to the object.
     78       
     79       Following the above example, if you knew the object ID was ``14`` but
     80       didn't have access to the actual object, you could do something like::
     81       
     82            {% get_comment_count for blog.entry 14 as comment_count %}
     83           
     84       In the above, ``blog.entry`` is the app label and (lower-cased) model
     85       name of the model class.
     86
     87.. templatetag:: get_comment_list
     88
     89Displaying comments
     90-------------------
     91
     92To get a the list of comments for some object, use :ttag:`get_comment_list`::
     93
     94    {% get_comment_list for [object] as [varname] %}
     95
     96For example::
     97
     98    {% get_comment_list for event as comment_list %}
     99    {% for comment in comment_list %}
     100        ...
     101    {% endfor %}
     102
     103.. templatetag:: get_comment_count
     104
     105Counting comments
     106-----------------
     107
     108To count comments attached to an object, use :ttag:`get_comment_count`::
     109
     110    {% get_comment_count for [object] as [varname]  %}
     111
     112For example::
     113
     114        {% get_comment_count for event as comment_count %}
     115       
     116        <p>This event has {{ comment_count }} comments.</p>
     117       
     118
     119Displaying the comment post form
     120--------------------------------
     121
     122To show the form that users will use to post a comment, you can use
     123:ttag:`render_comment_form` or :ttag:`get_comment_form`
     124
     125.. templatetag:: render_comment_form
     126
     127Quickly rendering the comment form
     128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     129
     130The easiest way to display a comment form is by using
     131:ttag:`render_comment_form`::
     132
     133    {% render_comment_form for [object] %}
     134
     135For example::
     136
     137    {% render_comment_form for event %}
     138
     139This will render comments using a template named ``comments/form.html``, a
     140default version of which is included with Django.
     141
     142.. templatetag:: get_comment_form
     143
     144Rendering a custom comment form
     145~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     146
     147If you want more control over the look and feel of the comment form, you use use
     148:ttag:`get_comment_form` to get a :ref:`form object <topics-forms-index>` that
     149you can use in the template::
     150
     151    {% get_comment_form for [object] as [varname] %}
     152   
     153A complete form might look like::
     154
     155    {% get_comment_form for event as form %}
     156    <form action="{% comment_form_target %}" method="POST">
     157      {{ form }}
     158      <p class="submit">
     159        <input type="submit" name="preview" class="submit-post" value="Preview">
     160      </p>
     161    </form>
     162   
     163Be sure to read the `notes on the comment form`_, below, for some special
     164considerations you'll need to make if you're using this aproach.
     165
     166.. templatetag:: comment_form_target
     167
     168Getting the comment form target
     169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     170
     171You may have noticed that the above example uses another template tag --
     172:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
     173form. This will always return the correct URL that comments should be posted to;
     174you'll always want to use it like above::
     175
     176    <form action="{% comment_form_target %}" method="POST">
     177
     178Specifying the redirect page after comment post
     179-----------------------------------------------
     180
     181To specify the page you want to redirect to after the comment has been
     182posted, you can include a hidden tag called ``next`` in your comment form::
     183
     184    <input type="hidden" name="next" value="page_to_redirect" />
     185
     186Redirecting after a preview or error
     187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     188
     189If you use the comment preview, or an error occurs in your comment post,
     190you will be taken to the template named ``comments/preview.html``. The value you specified for ``next``
     191on your post page isn't automatically carried over to the preview page.
     192
     193You need to again specify the redirect page with a hidden form tag::
     194
     195    <input type="hidden" name="next" value="{{ data.next }}" />
     196
     197``data`` contains all of the posted values from the original comment post
     198page. ``data.next`` gives us the value of ``next``.
     199
     200Notes on the comment form
     201-------------------------
     202
     203The form used by the comment system has a few important anti-spam attributes you
     204should know about:
     205
     206    * It contains a number of hidden fields that contain timestamps, information
     207      about the object the comment should be attached to, and a "security hash"
     208      used to validate this information. If someone tampers with this data --
     209      something comment spammers will try -- the comment submission will fail.
     210     
     211      If you're rendering a custom comment form, you'll need to make sure to
     212      pass these values through unchanged.
     213     
     214    * The timestamp is used to ensure that "reply attacks" can't continue very
     215      long. Users who wait too long between requesting the form and posting a
     216      comment will have their submissions refused.
     217     
     218    * The comment form includes a "honeypot_" field. It's a trap: if any data is
     219      entered in that field, the comment will be considered spam (spammers often
     220      automatically fill in all fields in an attempt to make valid submissions).
     221     
     222      The default form hides this field with a piece of CSS and further labels
     223      it with a warning field; if you use the comment form with a custom
     224      template you should be sure to do the same.
     225   
     226.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
     227
     228More information
     229================
     230
     231.. toctree::
     232   :maxdepth: 1
     233
     234   settings
     235   signals
     236   upgrade
     237
Back to Top