diff options
author | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
---|---|---|
committer | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
commit | 65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch) | |
tree | b4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/ref/contrib/comments/index.txt | |
parent | 2e35094d43b4cc6974172e1febf76abb50f086ec (diff) | |
download | pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.gz pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.bz2 pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.zip |
Added buildout stuff and made changes accordingly
--HG--
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt
rename : taskapp/models.py => parts/django/django/conf/app_template/models.py
rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py
rename : taskapp/views.py => parts/django/django/conf/app_template/views.py
rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py
rename : profile/forms.py => pytask/profile/forms.py
rename : profile/management/__init__.py => pytask/profile/management/__init__.py
rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py
rename : profile/models.py => pytask/profile/models.py
rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py
rename : taskapp/tests.py => pytask/profile/tests.py
rename : profile/urls.py => pytask/profile/urls.py
rename : profile/utils.py => pytask/profile/utils.py
rename : profile/views.py => pytask/profile/views.py
rename : static/css/base.css => pytask/static/css/base.css
rename : taskapp/tests.py => pytask/taskapp/tests.py
rename : taskapp/views.py => pytask/taskapp/views.py
rename : templates/base.html => pytask/templates/base.html
rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html
rename : templates/profile/edit.html => pytask/templates/profile/edit.html
rename : templates/profile/view.html => pytask/templates/profile/view.html
rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html
rename : templates/registration/activate.html => pytask/templates/registration/activate.html
rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt
rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt
rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html
rename : templates/registration/login.html => pytask/templates/registration/login.html
rename : templates/registration/logout.html => pytask/templates/registration/logout.html
rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html
rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html
rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html
rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html
rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html
rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html
rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html
rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html
rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html
rename : utils.py => pytask/utils.py
Diffstat (limited to 'parts/django/docs/ref/contrib/comments/index.txt')
-rw-r--r-- | parts/django/docs/ref/contrib/comments/index.txt | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/comments/index.txt b/parts/django/docs/ref/contrib/comments/index.txt new file mode 100644 index 0000000..817871e --- /dev/null +++ b/parts/django/docs/ref/contrib/comments/index.txt @@ -0,0 +1,302 @@ +=========================== +Django's comments framework +=========================== + +.. module:: django.contrib.comments + :synopsis: Django's comment framework + +.. highlightlang:: html+django + +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 :doc:`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 :doc:`/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. + +Displaying comments +------------------- + +To display a list of comments, you can use the template tags +:ttag:`render_comment_list` or :ttag:`get_comment_list`. + +.. templatetag:: render_comment_list + +Quickly rendering a comment list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest way to display a list of comments for some object is by using +:ttag:`render_comment_list`:: + + {% render_comment_list for [object] %} + +For example:: + + {% render_comment_list for event %} + +This will render comments using a template named ``comments/list.html``, a +default version of which is included with Django. + +.. templatetag:: get_comment_list + +Rendering a custom comment list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get 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 %} + +This returns a list of :class:`~django.contrib.comments.models.Comment` objects; +see :doc:`the comment model documentation </ref/contrib/comments/models>` for +details. + +.. templatetag:: get_comment_permalink + +Linking to comments +------------------- + +.. versionadded:: 1.2 + +To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`:: + + {% get_comment_permalink comment_obj [format_string] %} + +By default, the named anchor that will be appended to the URL will be the letter +'c' followed by the comment id, for example 'c82'. You may specify a custom +format string if you wish to override this behavior:: + + {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%} + +The format string is a standard python format string. Valid mapping keys +include any attributes of the comment object. + +Regardless of whether you specify a custom anchor pattern, you must supply a +matching named anchor at a suitable place in your template. + +For example:: + + {% for comment in comment_list %} + <a name="c{{ comment.id }}"></a> + <a href="{% get_comment_permalink comment %}"> + permalink for comment #{{ forloop.counter }} + </a> + ... + {% endfor %} + +.. warning:: + + There's a known bug in Safari/Webkit which causes the named anchor to be + forgotten following a redirect. The practical impact for comments is that + the Safari/webkit browsers will arrive at the correct page but will not + scroll to the named anchor. + +.. 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 :doc:`form object </topics/forms/index>` that +you can use in the template:: + + {% get_comment_form for [object] as [varname] %} + +A complete form might look like:: + + {% get_comment_form for event as form %} + <form action="{% comment_form_target %}" method="post"> + {{ form }} + <tr> + <td></td> + <td><input type="submit" name="preview" class="submit-post" value="Preview"></td> + </tr> + </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 approach. + +.. 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"> + +Redirecting after the comment post +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the URL you want to redirect to after the comment has been posted, +you can include a hidden form input called ``next`` in your comment form. For example:: + + <input type="hidden" name="next" value="{% url my_comment_was_posted %}" /> + +.. _notes-on-the-comment-form: + +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. + +The comments app also depends on the more general :doc:`Cross Site Request +Forgery protection </ref/contrib/csrf>` that comes with Django. As described in +the documentation, it is best to use ``CsrfViewMiddleware``. However, if you +are not using that, you will need to use the ``csrf_protect`` decorator on any +views that include the comment form, in order for those views to be able to +output the CSRF token and cookie. + +.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing) + +More information +================ + +.. toctree:: + :maxdepth: 1 + + models + settings + signals + upgrade + custom + forms + moderation + example |