/docs/ref/contrib/comments/moderation.txt

  1==========================
  2Generic comment moderation
  3==========================
  4
  5.. module:: django.contrib.comments.moderation
  6   :synopsis: Support for automatic comment moderation.
  7
  8Django's bundled comments application is extremely useful on its own,
  9but the amount of comment spam circulating on the Web today
 10essentially makes it necessary to have some sort of automatic
 11moderation system in place for any application which makes use of
 12comments. To make this easier to handle in a consistent fashion,
 13``django.contrib.comments.moderation`` provides a generic, extensible
 14comment-moderation system which can be applied to any model or set of
 15models which want to make use of Django's comment system.
 16
 17
 18Overview
 19========
 20
 21The entire system is contained within ``django.contrib.comments.moderation``,
 22and uses a two-step process to enable moderation for any given model:
 23
 241. A subclass of :class:`CommentModerator`
 25   is defined which specifies the moderation options the model wants to
 26   enable.
 27
 282. The model is registered with the moderation system, passing in the
 29   model class and the class which specifies its moderation options.
 30
 31A simple example is the best illustration of this. Suppose we have the
 32following model, which would represent entries in a Weblog::
 33
 34    from django.db import models
 35    
 36    class Entry(models.Model):
 37        title = models.CharField(maxlength=250)
 38        body = models.TextField()
 39        pub_date = models.DateTimeField()
 40        enable_comments = models.BooleanField()
 41
 42Now, suppose that we want the following steps to be applied whenever a
 43new comment is posted on an ``Entry``:
 44
 451. If the ``Entry``'s ``enable_comments`` field is ``False``, the
 46   comment will simply be disallowed (i.e., immediately deleted).
 47
 482. If the ``enable_comments`` field is ``True``, the comment will be
 49   allowed to save.
 50
 513. Once the comment is saved, an email should be sent to site staff
 52   notifying them of the new comment.
 53
 54Accomplishing this is fairly straightforward and requires very little
 55code::
 56
 57    from django.contrib.comments.moderation import CommentModerator, moderator
 58    
 59    class EntryModerator(CommentModerator):
 60        email_notification = True
 61        enable_field = 'enable_comments'
 62    
 63    moderator.register(Entry, EntryModerator)
 64
 65The :class:`CommentModerator` class pre-defines a number of useful moderation
 66options which subclasses can enable or disable as desired, and ``moderator``
 67knows how to work with them to determine whether to allow a comment, whether
 68to moderate a comment which will be allowed to post, and whether to email
 69notifications of new comments.
 70
 71Built-in moderation options
 72---------------------------
 73
 74.. class:: CommentModerator
 75
 76    Most common comment-moderation needs can be handled by subclassing
 77    :class:`CommentModerator` and
 78    changing the values of pre-defined attributes; the full range of built-in
 79    options is as follows.
 80
 81    .. attribute:: auto_close_field
 82
 83        If this is set to the name of a
 84        :class:`~django.db.models.fields.DateField` or
 85        :class:`~django.db.models.fields.DateTimeField` on the model for which
 86        comments are being moderated, new comments for objects of that model
 87        will be disallowed (immediately deleted) when a certain number of days
 88        have passed after the date specified in that field. Must be
 89        used in conjunction with :attr:`close_after`, which specifies the
 90        number of days past which comments should be
 91        disallowed. Default value is ``None``.
 92
 93    .. attribute:: auto_moderate_field
 94
 95        Like :attr:`auto_close_field`, but instead of outright deleting
 96        new comments when the requisite number of days have elapsed,
 97        it will simply set the ``is_public`` field of new comments to
 98        ``False`` before saving them. Must be used in conjunction with
 99        :attr:`moderate_after`, which specifies the number of days past
100        which comments should be moderated. Default value is ``None``.
101
102    .. attribute:: close_after
103
104        If :attr:`auto_close_field` is used, this must specify the number
105        of days past the value of the field specified by
106        :attr:`auto_close_field` after which new comments for an object
107        should be disallowed. Allowed values are ``None``, 0 (which disallows
108        comments immediately), or any positive integer. Default value is
109        ``None``.
110
111    .. attribute:: email_notification
112
113        If ``True``, any new comment on an object of this model which
114        survives moderation (i.e., is not deleted) will generate an
115        email to site staff. Default value is ``False``.
116
117    .. attribute:: enable_field
118
119        If this is set to the name of a
120        :class:`~django.db.models.fields.BooleanField` on the model
121        for which comments are being moderated, new comments on
122        objects of that model will be disallowed (immediately deleted)
123        whenever the value of that field is ``False`` on the object
124        the comment would be attached to. Default value is ``None``.
125
126    .. attribute:: moderate_after
127
128        If :attr:`auto_moderate_field` is used, this must specify the number
129        of days past the value of the field specified by
130        :attr:`auto_moderate_field` after which new comments for an object
131        should be marked non-public. Allowed values are ``None``, 0 (which
132        moderates comments immediately), or any positive integer. Default
133        value is ``None``.
134
135Simply subclassing :class:`CommentModerator` and changing the values of these
136options will automatically enable the various moderation methods for any
137models registered using the subclass.
138
139.. versionchanged:: 1.3
140
141``moderate_after`` and ``close_after`` now accept 0 as a valid value.
142
143Adding custom moderation methods
144--------------------------------
145
146For situations where the built-in options listed above are not
147sufficient, subclasses of :class:`CommentModerator` can also override
148the methods which actually perform the moderation, and apply any logic
149they desire.  :class:`CommentModerator` defines three methods which
150determine how moderation will take place; each method will be called
151by the moderation system and passed two arguments: ``comment``, which
152is the new comment being posted, ``content_object``, which is the
153object the comment will be attached to, and ``request``, which is the
154:class:`~django.http.HttpRequest` in which the comment is being submitted:
155
156.. method:: CommentModerator.allow(comment, content_object, request)
157
158    Should return ``True`` if the comment should be allowed to
159    post on the content object, and ``False`` otherwise (in which
160    case the comment will be immediately deleted).
161
162.. method:: CommentModerator.email(comment, content_object, request)
163
164    If email notification of the new comment should be sent to
165    site staff or moderators, this method is responsible for
166    sending the email.
167
168.. method:: CommentModerator.moderate(comment, content_object, request)
169
170    Should return ``True`` if the comment should be moderated (in
171    which case its ``is_public`` field will be set to ``False``
172    before saving), and ``False`` otherwise (in which case the
173    ``is_public`` field will not be changed).
174
175
176Registering models for moderation
177---------------------------------
178
179The moderation system, represented by
180``django.contrib.comments.moderation.moderator`` is an instance of the class
181:class:`Moderator`, which allows registration and "unregistration" of models
182via two methods:
183
184.. function:: moderator.register(model_or_iterable, moderation_class)
185
186    Takes two arguments: the first should be either a model class
187    or list of model classes, and the second should be a subclass
188    of ``CommentModerator``, and register the model or models to
189    be moderated using the options defined in the
190    ``CommentModerator`` subclass. If any of the models are
191    already registered for moderation, the exception
192    :exc:`AlreadyModerated` will be raised.
193
194.. function:: moderator.unregister(model_or_iterable)
195
196    Takes one argument: a model class or list of model classes,
197    and removes the model or models from the set of models which
198    are being moderated. If any of the models are not currently
199    being moderated, the exception
200    :exc:`NotModerated` will be raised.
201
202
203Customizing the moderation system
204---------------------------------
205
206Most use cases will work easily with simple subclassing of
207:class:`CommentModerator` and registration with the provided
208:class:`Moderator` instance, but customization of global moderation behavior
209can be achieved by subclassing :class:`Moderator` and instead registering
210models with an instance of the subclass.
211
212.. class:: Moderator
213
214    In addition to the :meth:`Moderator.register` and
215    :meth:`Moderator.unregister` methods detailed above, the following methods
216    on :class:`Moderator` can be overridden to achieve customized behavior:
217
218    .. method:: connect
219
220        Determines how moderation is set up globally. The base
221        implementation in
222        :class:`Moderator` does this by
223        attaching listeners to the :data:`~django.contrib.comments.signals.comment_will_be_posted`
224        and :data:`~django.contrib.comments.signals.comment_was_posted` signals from the
225        comment models.
226
227    .. method:: pre_save_moderation(sender, comment, request, **kwargs)
228
229        In the base implementation, applies all pre-save moderation
230        steps (such as determining whether the comment needs to be
231        deleted, or whether it needs to be marked as non-public or
232        generate an email).
233
234    .. method:: post_save_moderation(sender, comment, request, **kwargs)
235
236        In the base implementation, applies all post-save moderation
237        steps (currently this consists entirely of deleting comments
238        which were disallowed).