Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Oops, added missing file from [10122].

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10123 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit f22418a6becb80770e83eab0fc38190a73f89ed3 1 parent f0560df
Jacob Kaplan-Moss authored March 23, 2009

Showing 1 changed file with 235 additions and 0 deletions. Show diff stats Hide diff stats

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

0 notes on commit f22418a

Please sign in to comment.
Something went wrong with that request. Please try again.