python/lib/django_1_4/docs/ref/contrib/comments/moderation.txt

   1 ==========================
   2 Generic comment moderation
   3 ==========================
   4
   5 .. module:: django.contrib.comments.moderation
   6    :synopsis: Support for automatic comment moderation.
   7
   8 Django's bundled comments application is extremely useful on its own,
   9 but the amount of comment spam circulating on the Web today
  10 essentially makes it necessary to have some sort of automatic
  11 moderation system in place for any application which makes use of
  12 comments. To make this easier to handle in a consistent fashion,
  13 ``django.contrib.comments.moderation`` provides a generic, extensible
  14 comment-moderation system which can be applied to any model or set of
  15 models which want to make use of Django's comment system.
  16
  17
  18 Overview
  19 ========
  20
  21 The entire system is contained within ``django.contrib.comments.moderation``,
  22 and uses a two-step process to enable moderation for any given model:
  23
  24 1. A subclass of :class:`CommentModerator`
  25    is defined which specifies the moderation options the model wants to
  26    enable.
  27
  28 2. The model is registered with the moderation system, passing in the
  29    model class and the class which specifies its moderation options.
  30
  31 A simple example is the best illustration of this. Suppose we have the
  32 following 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
  42 Now, suppose that we want the following steps to be applied whenever a
  43 new comment is posted on an ``Entry``:
  44
  45 1. If the ``Entry``'s ``enable_comments`` field is ``False``, the
  46    comment will simply be disallowed (i.e., immediately deleted).
  47
  48 2. If the ``enable_comments`` field is ``True``, the comment will be
  49    allowed to save.
  50
  51 3. Once the comment is saved, an email should be sent to site staff
  52    notifying them of the new comment.
  53
  54 Accomplishing this is fairly straightforward and requires very little
  55 code::
  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
  65 The :class:`CommentModerator` class pre-defines a number of useful moderation
  66 options which subclasses can enable or disable as desired, and ``moderator``
  67 knows how to work with them to determine whether to allow a comment, whether
  68 to moderate a comment which will be allowed to post, and whether to email
  69 notifications of new comments.
  70
  71 Built-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
 135 Simply subclassing :class:`CommentModerator` and changing the values of these
 136 options will automatically enable the various moderation methods for any
 137 models registered using the subclass.
 138
 139 .. versionchanged:: 1.3
 140
 141 ``moderate_after`` and ``close_after`` now accept 0 as a valid value.
 142
 143 Adding custom moderation methods
 144 --------------------------------
 145
 146 For situations where the built-in options listed above are not
 147 sufficient, subclasses of :class:`CommentModerator` can also override
 148 the methods which actually perform the moderation, and apply any logic
 149 they desire.  :class:`CommentModerator` defines three methods which
 150 determine how moderation will take place; each method will be called
 151 by the moderation system and passed two arguments: ``comment``, which
 152 is the new comment being posted, ``content_object``, which is the
 153 object 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
 176 Registering models for moderation
 177 ---------------------------------
 178
 179 The 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
 182 via 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
 203 Customizing the moderation system
 204 ---------------------------------
 205
 206 Most 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
 209 can be achieved by subclassing :class:`Moderator` and instead registering
 210 models 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).