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

https://code.google.com/p/mango-py/ · Plain Text · 238 lines · 175 code · 63 blank · 0 comment · 0 complexity · eacdf3f49c0eb72dfab217bf7edeb15f MD5 · raw file

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