/docs/ref/contrib/comments/moderation.txt
Plain Text | 238 lines | 175 code | 63 blank | 0 comment | 0 complexity | eacdf3f49c0eb72dfab217bf7edeb15f MD5 | raw file
Possible License(s): BSD-3-Clause
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).