/docs/ref/contrib/comments/custom.txt

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