Ticket #8630: 8630_r9084.diff

django/contrib/comments/admin.py

@@ -2 +2 @@
 from django.conf import settings
 from django.contrib.comments.models import Comment
 from django.utils.translation import ugettext_lazy as _
+from django.contrib.comments import get_model
 
 class CommentsAdmin(admin.ModelAdmin):
     fieldsets = (
@@ -22 +23 @@
     ordering = ('-submit_date',)
     search_fields = ('comment', 'user__username', 'user_name', 'user_email', 'user_url', 'ip_address')
 
-admin.site.register(Comment, CommentsAdmin)
+if get_model() is Comment:
+    admin.site.register(Comment, CommentsAdmin)

django/contrib/comments/__init__.py

@@ -2 +2 @@
 from django.core import urlresolvers
 from django.core.exceptions import ImproperlyConfigured
 
-# Attributes required in the top-level app for COMMENTS_APP
-REQUIRED_COMMENTS_APP_ATTRIBUTES = ["get_model", "get_form", "get_form_target"]
-
 def get_comment_app():
     """
     Get the comment app (i.e. "django.contrib.comments") as defined in the settings
@@ -22 +19 @@
         raise ImproperlyConfigured("The COMMENTS_APP setting refers to "\
                                    "a non-existing package.")
 
-    # Make sure some specific attributes exist inside that package.
-    for attribute in REQUIRED_COMMENTS_APP_ATTRIBUTES:
-        if not hasattr(package, attribute):
-            raise ImproperlyConfigured("The COMMENTS_APP package %r does not "\
-                                       "define the (required) %r function" % \
-                                            (package, attribute))
-
     return package
 
 def get_comment_app_name():
@@ -39 +29 @@
     return getattr(settings, 'COMMENTS_APP', 'django.contrib.comments')
 
 def get_model():
+    if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_model"):
+        return get_comment_app().get_model()
     from django.contrib.comments.models import Comment
     return Comment
 
 def get_form():
+    if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_form"):
+        return get_comment_app().get_form()
     from django.contrib.comments.forms import CommentForm
     return CommentForm
 
 def get_form_target():
+    if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_form_target"):
+        return get_comment_app().get_form_target()
     return urlresolvers.reverse("django.contrib.comments.views.comments.post_comment")
 
 def get_flag_url(comment):
@@ -55 +51 @@
     """
     if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_flag_url"):
         return get_comment_app().get_flag_url(comment)
-    else:
-        return urlresolvers.reverse("django.contrib.comments.views.moderation.flag", args=(comment.id,))
+    return urlresolvers.reverse("django.contrib.comments.views.moderation.flag", args=(comment.id,))
 
 def get_delete_url(comment):
     """
     Get the URL for the "delete this comment" view.
     """
     if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_delete_url"):
-        return get_comment_app().get_flag_url(get_delete_url)
-    else:
-        return urlresolvers.reverse("django.contrib.comments.views.moderation.delete", args=(comment.id,))
+        return get_comment_app().get_delete_url(comment)
+    return urlresolvers.reverse("django.contrib.comments.views.moderation.delete", args=(comment.id,))
 
 def get_approve_url(comment):
     """
@@ -73 +67 @@
     """
     if get_comment_app_name() != __name__ and hasattr(get_comment_app(), "get_approve_url"):
         return get_comment_app().get_approve_url(comment)
-    else:
-        return urlresolvers.reverse("django.contrib.comments.views.moderation.approve", args=(comment.id,))
+    return urlresolvers.reverse("django.contrib.comments.views.moderation.approve", args=(comment.id,))

docs/ref/contrib/comments/index.txt

@@ -175 +175 @@
 
     <form action="{% comment_form_target %}" method="POST">
 
+.. _notes-on-the-comment-form:
+
 Notes on the comment form
 -------------------------
 
@@ -212 +214 @@
    settings
    signals
    upgrade
-
+   custom

docs/ref/contrib/comments/custom.txt

@@ +1 @@
+.. _ref-contrib-comments-custom:
+
+==================================
+Customizing the comments framework
+==================================
+
+Via the :setting:`COMMENTS_APP` setting, the comments framework allows
+you to replace the built-in comment model and comment form with your
+own classes.
+
+The COMMENTS_APP
+================
+
+A custom :setting:`COMMENTS_APP` should define one or more of the
+following module-level functions in it's ``__init__.py`` file. None of
+these functions are required, so you can define any combination of
+them (all others will use the defaults from
+``django.contrib.comments``):
+
+.. function:: get_model()
+
+    Return the :class:`~django.db.models.Model` class to use for
+    comments.  This model should inherit from
+    :class:`django.contrib.comments.models.BaseCommentAbstractModel`,
+    which defines necessary core fields.
+
+    The default implementation returns
+    :class:`django.contrib.comments.models.Comment`.
+
+.. function:: get_form()
+
+    Return the :class:`~django.forms.Form` class you want to use for
+    creating, validating, and saving your comment model.  Your custom
+    comment form should accept an additional first argument,
+    ``target_object``, which is the object the comment will be
+    attached to.
+
+    The default implementation returns
+    :class:`django.contrib.comments.forms.CommentForm`.
+
+    .. note::
+        
+        The default comment form also includes a number of unobtrusive
+        spam-prevention features (see
+        :ref:`notes-on-the-comment-form`).  If replacing it with your
+        own form, you may want to look at the source code for the
+        built-in form and consider incorporating similar features.
+
+.. function:: get_form_target()
+
+    Return the URL for POSTing comments.  This will be the ``action``
+    attribute when rendering your comment form.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`post_comment` view.
+
+    .. note::
+
+        If you provide a custom comment model and/or form, but you
+        want to use the default :func:`post_comment` view, you will
+        need to be aware that it requires the model and form to have
+        certain additional attributes and methods: see the
+        :func:`post_comment` view documentation for details.
+
+.. function:: get_flag_url()
+
+    Return the URL for the "flag this comment" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.flag` view.
+
+.. function:: get_delete_url()
+
+    Return the URL for the "delete this comment" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.delete` view.
+
+.. function:: get_approve_url()
+
+    Return the URL for the "approve this comment from moderation" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.approve` view.
+
+A sample custom comments app
+----------------------------
+
+A custom comments app might have an ``__init__.py`` like this::
+
+    from django.core.urlresolvers import reverse
+
+    def get_model():
+        from my_comments_app.models import MyComment
+        return MyComment
+
+    def get_form():
+        from my_comments_app.forms import MyCommentForm
+        return MyCommentForm
+
+    def get_form_target():
+        return reverse('my_comments_app.views.post_comment')
+
+
+``MyComment`` should inherit from :class:`BaseCommentAbstractModel`,
+so in ``models.py``::
+
+    from django.db import models
+    from django.contrib.comments.models import BaseCommentAbstractModel
+    
+    class MyComment(BaseCommentAbstractModel):
+        ... fields and custom methods ...
+
+And ``MyCommentForm`` should accept a target_object argument,
+so in ``forms.py``::
+
+    from django import forms
+
+    class MyCommentForm(forms.Form):
+        def __init__(self, target_object, data=None, initial=None):
+            ...
+
+In order to enable this custom comments app, you would need to have
+the following in your project's ``settings.py``::
+
+    INSTALLED_APPS = (
+    ...
+    'my_comments_app',
+    ...
+    )
+
+    COMMENTS_APP = 'my_comments_app'
+
+
+API reference
+==================================
+
+BaseCommentAbstractModel
+------------------------
+
+.. class:: BaseCommentAbstractModel
+
+    :class:`BaseCommentAbstractModel` defines the following attributes
+    and methods, which your custom comment model will inherit:
+
+    .. attribute:: site
+
+        A foreign key to the
+        :class:`~django.contrib.sites.models.Site` model (see
+        :ref:`ref-contrib-sites`), defining which site this comment
+        appears on.
+
+    .. attribute:: content_type
+
+        A foreign key to the
+        :class:`~django.contrib.contenttypes.models.ContentType`
+        model.  This is the content type of the target object the
+        comment is attached to.
+
+    .. attribute:: object_pk
+
+        The primary key of the target object.
+
+    .. attribute:: content_object
+
+        A
+        :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
+        to the target object, using the :attr:`content_type` and
+        :attr:`object_pk` attributes.
+
+    .. method:: get_content_object_url()
+
+        Returns a URL that redirects to the URL of the comment's
+        target object.
+
+post_comment view
+-----------------
+
+.. function:: post_comment
+
+    The default :func:`post_comment` view requires the comment model
+    to have two additional fields:
+
+    .. attribute:: user
+
+        This should be a :class:`ForeignKey` to the :class:`User`
+        model.  The view will store the user who posted the comment in
+        this field.
+
+    .. attribute:: ip_address
+
+        This should be an :class:`IPAddressField`.  The
+        :func:`post_comment` view will store the remote IP address of
+        the comment poster in it.
+
+    The :func:`post_comment` view also requires the comment form to
+    have the following two methods:
+
+    .. method:: security_errors()
+
+        If this method returns a false value, the form will be
+        considered to have passed anti-spam screening.  If it returns
+        any nonzero value, that value will be coerced to a string and
+        sent as part of an HTTP 400 (bad request) response.
+
+    .. method:: get_comment_object()
+
+        This method will only be called if the form has passed
+        validation and returned no :func:`security_errors()`.  It
+        should return an (unsaved) comment object, which will be
+        annotated with the user and IP address and then saved.

docs/ref/contrib/comments/settings.txt

@@ -29 +29 @@
 COMMENTS_APP
 ------------
 
-The app (i.e. entry in ``INSTALLED_APPS``) responsible for all "business logic."
-You can change this to provide custom comment models and forms, though this is
-currently undocumented.
+An app which provides :ref:`customization of the comments framework
+<ref-contrib-comments-custom>`.  Use the same dotted-string notation
+as in :setting:`INSTALLED_APPS`.  Your custom :setting:`COMMENTS_APP`
+must also be listed in :setting:`INSTALLED_APPS`.