← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/ref/contrib/comments/custom.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2009-07-29 11:26:28 UTC
  • mfrom: (1.1.8 upstream) (4.1.5 sid)
  • Revision ID: james.westby@ubuntu.com-20090729112628-pg09ino8sz0sj21t
Tags: 1.1-1
http://bugs.debian.org/538863
* New upstream release.
* Merge from experimental:
  - Ship FastCGI initscript and /etc/default file in python-django's examples
    directory (Closes: #538863)
  - Drop "05_10539-sphinx06-compatibility.diff"; it has been applied
    upstream.
  - Bump Standards-Version to 3.8.2.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/comments/custom.txt
 
1
.. _ref-contrib-comments-custom:
 
2
 
 
3
==================================
 
4
Customizing the comments framework
 
5
==================================
 
6
 
 
7
.. currentmodule:: django.contrib.comments
 
8
 
 
9
If the built-in comment framework doesn't quite fit your needs, you can extend
 
10
the comment app's behavior to add custom data and logic. The comments framework
 
11
lets you extend the built-in comment model, the built-in comment form, and the
 
12
various comment views.
 
13
 
 
14
The :setting:`COMMENTS_APP` setting is where this customization begins. Set
 
15
:setting:`COMMENTS_APP` to the name of the app you'd like to use to provide
 
16
custom behavior. You'll use the same syntax as you'd use for
 
17
:setting:`INSTALLED_APPS`, and the app given must also be in the
 
18
:setting:`INSTALLED_APPS` list.
 
19
 
 
20
For example, if you wanted to use an app named ``my_comment_app``, your
 
21
settings file would contain::
 
22
 
 
23
    INSTALLED_APPS = [
 
24
        ...
 
25
        'my_comment_app',
 
26
        ...
 
27
    ]
 
28
 
 
29
    COMMENTS_APP = 'my_comment_app'
 
30
 
 
31
The app named in :setting:`COMMENTS_APP` provides its custom behavior by
 
32
defining some module-level functions in the app's ``__init__.py``. The
 
33
:ref:`complete list of these functions <custom-comment-app-api>` can be found
 
34
below, but first let's look at a quick example.
 
35
 
 
36
An example custom comments app
 
37
==============================
 
38
 
 
39
One of the most common types of customization is modifying the set of fields
 
40
provided on the built-in comment model. For example, some sites that allow
 
41
comments want the commentator to provide a title for their comment; the built-in
 
42
comment model has no field for that title.
 
43
 
 
44
To make this kind of customization, we'll need to do three things:
 
45
 
 
46
    #. Create a custom comment :class:`~django.db.models.Model` that adds on the
 
47
       "title" field.
 
48
 
 
49
    #. Create a custom comment :class:`~django.forms.Form` that also adds this
 
50
       "title" field.
 
51
 
 
52
    #. Inform Django of these objects by defining a few functions in a
 
53
       custom :setting:`COMMENTS_APP`.
 
54
 
 
55
So, carrying on the example above, we're dealing with a typical app structure in
 
56
the ``my_custom_app`` directory::
 
57
 
 
58
    my_custom_app/
 
59
        __init__.py
 
60
        models.py
 
61
        forms.py
 
62
 
 
63
In the ``models.py`` we'll define a ``CommentWithTitle`` model::
 
64
 
 
65
    from django.db import models
 
66
    from django.contrib.comments.models import Comment
 
67
 
 
68
    class CommentWithTitle(Comment):
 
69
        title = models.CharField(max_length=300)
 
70
 
 
71
Most custom comment models will subclass the :class:`Comment` model. However,
 
72
if you want to substantially remove or change the fields available in the
 
73
:class:`Comment` model, but don't want to rewrite the templates, you could
 
74
try subclassing from :class:`BaseCommentAbstractModel`.
 
75
 
 
76
Next, we'll define a custom comment form in ``forms.py``. This is a little more
 
77
tricky: we have to both create a form and override
 
78
:meth:`CommentForm.get_comment_model` and
 
79
:meth:`CommentForm.get_comment_create_data` to return deal with our custom title
 
80
field::
 
81
 
 
82
    from django import forms
 
83
    from django.contrib.comments.forms import CommentForm
 
84
    from my_comment_app.models import CommentWithTitle
 
85
 
 
86
    class CommentFormWithTitle(CommentForm):
 
87
        title = forms.CharField(max_length=300)
 
88
 
 
89
        def get_comment_model(self):
 
90
            # Use our custom comment model instead of the built-in one.
 
91
            return CommentWithTitle
 
92
 
 
93
        def get_comment_create_data(self):
 
94
            # Use the data of the superclass, and add in the title field
 
95
            data = super(CommentFormWithTitle, self).get_comment_create_data()
 
96
            data['title'] = self.cleaned_data['title']
 
97
            return data
 
98
 
 
99
Django provides a couple of "helper" classes to make writing certain types of
 
100
custom comment forms easier; see :mod:`django.contrib.comments.forms` for
 
101
more.
 
102
 
 
103
Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
 
104
point Django at these classes we've created::
 
105
 
 
106
    from my_comments_app.models import CommentWithTitle
 
107
    from my_comments_app.forms import CommentFormWithTitle
 
108
 
 
109
    def get_model():
 
110
        return CommentWithTitle
 
111
 
 
112
    def get_form():
 
113
        return CommentFormWithTitle
 
114
 
 
115
The above process should take care of most common situations. For more
 
116
advanced usage, there are additional methods you can define. Those are
 
117
explained in the next section.
 
118
 
 
119
.. _custom-comment-app-api:
 
120
 
 
121
Custom comment app API
 
122
======================
 
123
 
 
124
The :mod:`django.contrib.comments` app defines the following methods; any
 
125
custom comment app must define at least one of them. All are optional,
 
126
however.
 
127
 
 
128
.. function:: get_model()
 
129
 
 
130
    Return the :class:`~django.db.models.Model` class to use for comments. This
 
131
    model should inherit from
 
132
    :class:`django.contrib.comments.models.BaseCommentAbstractModel`, which
 
133
    defines necessary core fields.
 
134
 
 
135
    The default implementation returns
 
136
    :class:`django.contrib.comments.models.Comment`.
 
137
 
 
138
.. function:: get_form()
 
139
 
 
140
    Return the :class:`~django.forms.Form` class you want to use for
 
141
    creating, validating, and saving your comment model.  Your custom
 
142
    comment form should accept an additional first argument,
 
143
    ``target_object``, which is the object the comment will be
 
144
    attached to.
 
145
 
 
146
    The default implementation returns
 
147
    :class:`django.contrib.comments.forms.CommentForm`.
 
148
 
 
149
    .. note::
 
150
 
 
151
        The default comment form also includes a number of unobtrusive
 
152
        spam-prevention features (see
 
153
        :ref:`notes-on-the-comment-form`).  If replacing it with your
 
154
        own form, you may want to look at the source code for the
 
155
        built-in form and consider incorporating similar features.
 
156
 
 
157
.. function:: get_form_target()
 
158
 
 
159
    Return the URL for POSTing comments. This will be the ``<form action>``
 
160
    attribute when rendering your comment form.
 
161
 
 
162
    The default implementation returns a reverse-resolved URL pointing
 
163
    to the :func:`post_comment` view.
 
164
 
 
165
    .. note::
 
166
 
 
167
        If you provide a custom comment model and/or form, but you
 
168
        want to use the default :func:`post_comment` view, you will
 
169
        need to be aware that it requires the model and form to have
 
170
        certain additional attributes and methods: see the
 
171
        :func:`post_comment` view documentation for details.
 
172
 
 
173
.. function:: get_flag_url()
 
174
 
 
175
    Return the URL for the "flag this comment" view.
 
176
 
 
177
    The default implementation returns a reverse-resolved URL pointing
 
178
    to the :func:`django.contrib.comments.views.moderation.flag` view.
 
179
 
 
180
.. function:: get_delete_url()
 
181
 
 
182
    Return the URL for the "delete this comment" view.
 
183
 
 
184
    The default implementation returns a reverse-resolved URL pointing
 
185
    to the :func:`django.contrib.comments.views.moderation.delete` view.
 
186
 
 
187
.. function:: get_approve_url()
 
188
 
 
189
    Return the URL for the "approve this comment from moderation" view.
 
190
 
 
191
    The default implementation returns a reverse-resolved URL pointing
 
192
    to the :func:`django.contrib.comments.views.moderation.approve` view.