revision-up-to: | 17812 (1.4) unfinished |
---|
Django’s bundled comments application is extremely useful on its own,
but the amount of comment spam circulating on the Web today
essentially makes it necessary to have some sort of automatic
moderation system in place for any application which makes use of
comments. To make this easier to handle in a consistent fashion,
django.contrib.comments.moderation
provides a generic, extensible
comment-moderation system which can be applied to any model or set of
models which want to make use of Django’s comment system.
The entire system is contained within django.contrib.comments.moderation
,
and uses a two-step process to enable moderation for any given model:
CommentModerator
is defined which specifies the moderation options the model wants to
enable.A simple example is the best illustration of this. Suppose we have the following model, which would represent entries in a Weblog:
from django.db import models
class Entry(models.Model):
title = models.CharField(maxlength=250)
body = models.TextField()
pub_date = models.DateTimeField()
enable_comments = models.BooleanField()
Now, suppose that we want the following steps to be applied whenever a
new comment is posted on an Entry
:
Entry
‘s enable_comments
field is False
, the
comment will simply be disallowed (i.e., immediately deleted).enable_comments
field is True
, the comment will be
allowed to save.Accomplishing this is fairly straightforward and requires very little code:
from django.contrib.comments.moderation import CommentModerator, moderator
class EntryModerator(CommentModerator):
email_notification = True
enable_field = 'enable_comments'
moderator.register(Entry, EntryModerator)
The CommentModerator
class pre-defines a number of useful moderation
options which subclasses can enable or disable as desired, and moderator
knows how to work with them to determine whether to allow a comment, whether
to moderate a comment which will be allowed to post, and whether to email
notifications of new comments.
CommentModerator
¶Most common comment-moderation needs can be handled by subclassing
CommentModerator
and
changing the values of pre-defined attributes; the full range of built-in
options is as follows.
auto_close_field
¶If this is set to the name of a
DateField
or
DateTimeField
on the model for which
comments are being moderated, new comments for objects of that model
will be disallowed (immediately deleted) when a certain number of days
have passed after the date specified in that field. Must be
used in conjunction with close_after
, which specifies the
number of days past which comments should be
disallowed. Default value is None
.
auto_moderate_field
¶Like auto_close_field
, but instead of outright deleting
new comments when the requisite number of days have elapsed,
it will simply set the is_public
field of new comments to
False
before saving them. Must be used in conjunction with
moderate_after
, which specifies the number of days past
which comments should be moderated. Default value is None
.
close_after
¶If auto_close_field
is used, this must specify the number
of days past the value of the field specified by
auto_close_field
after which new comments for an object
should be disallowed. Allowed values are None
, 0 (which disallows
comments immediately), or any positive integer. Default value is
None
.
email_notification
¶If True
, any new comment on an object of this model which
survives moderation (i.e., is not deleted) will generate an
email to site staff. Default value is False
.
enable_field
¶If this is set to the name of a
BooleanField
on the model
for which comments are being moderated, new comments on
objects of that model will be disallowed (immediately deleted)
whenever the value of that field is False
on the object
the comment would be attached to. Default value is None
.
moderate_after
¶If auto_moderate_field
is used, this must specify the number
of days past the value of the field specified by
auto_moderate_field
after which new comments for an object
should be marked non-public. Allowed values are None
, 0 (which
moderates comments immediately), or any positive integer. Default
value is None
.
Simply subclassing CommentModerator
and changing the values of these
options will automatically enable the various moderation methods for any
models registered using the subclass.
リリースノートを参照してください
moderate_after
and close_after
now accept 0 as a valid value.
For situations where the built-in options listed above are not
sufficient, subclasses of CommentModerator
can also override
the methods which actually perform the moderation, and apply any logic
they desire. CommentModerator
defines three methods which
determine how moderation will take place; each method will be called
by the moderation system and passed two arguments: comment
, which
is the new comment being posted, content_object
, which is the
object the comment will be attached to, and request
, which is the
HttpRequest
in which the comment is being submitted:
CommentModerator.
allow
(comment, content_object, request)¶Should return True
if the comment should be allowed to
post on the content object, and False
otherwise (in which
case the comment will be immediately deleted).
CommentModerator.
email
(comment, content_object, request)¶If email notification of the new comment should be sent to site staff or moderators, this method is responsible for sending the email.
CommentModerator.
moderate
(comment, content_object, request)¶Should return True
if the comment should be moderated (in
which case its is_public
field will be set to False
before saving), and False
otherwise (in which case the
is_public
field will not be changed).
The moderation system, represented by
django.contrib.comments.moderation.moderator
is an instance of the class
Moderator
, which allows registration and “unregistration” of models
via two methods:
moderator.
register
(model_or_iterable, moderation_class)¶Takes two arguments: the first should be either a model class
or list of model classes, and the second should be a subclass
of CommentModerator
, and register the model or models to
be moderated using the options defined in the
CommentModerator
subclass. If any of the models are
already registered for moderation, the exception
AlreadyModerated
will be raised.
moderator.
unregister
(model_or_iterable)¶Takes one argument: a model class or list of model classes,
and removes the model or models from the set of models which
are being moderated. If any of the models are not currently
being moderated, the exception
NotModerated
will be raised.
Most use cases will work easily with simple subclassing of
CommentModerator
and registration with the provided
Moderator
instance, but customization of global moderation behavior
can be achieved by subclassing Moderator
and instead registering
models with an instance of the subclass.
Moderator
¶In addition to the Moderator.register()
and
Moderator.unregister()
methods detailed above, the following methods
on Moderator
can be overridden to achieve customized behavior:
connect
()¶Determines how moderation is set up globally. The base
implementation in
Moderator
does this by
attaching listeners to the comment_will_be_posted
and comment_was_posted
signals from the
comment models.
pre_save_moderation
(sender, comment, request, **kwargs)¶In the base implementation, applies all pre-save moderation steps (such as determining whether the comment needs to be deleted, or whether it needs to be marked as non-public or generate an email).
post_save_moderation
(sender, comment, request, **kwargs)¶In the base implementation, applies all post-save moderation steps (currently this consists entirely of deleting comments which were disallowed).
Oct 26, 2017