Ticket #10680: comments-doc-10278.diff

django/contrib/comments/forms.py

@@ -5 +5 @@
 from django.forms.util import ErrorDict
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
-from models import Comment
 from django.utils.encoding import force_unicode
 from django.utils.hashcompat import sha_constructor
 from django.utils.text import get_text_list
 from django.utils.translation import ungettext, ugettext_lazy as _
+from django.contrib.comments.models import Comment, BaseCommentAbstractModel
 
 COMMENT_MAX_LENGTH = getattr(settings,'COMMENT_MAX_LENGTH', 3000)
 
@@ -28 +28 @@
             initial = {}
         initial.update(self.generate_security_data())
         super(CommentSecurityForm, self).__init__(data=data, initial=initial)
-        
+
     def security_errors(self):
         """Return just those errors associated with security"""
         errors = ErrorDict()
@@ -86 +86 @@
         info = (content_type, object_pk, timestamp, settings.SECRET_KEY)
         return sha_constructor("".join(info)).hexdigest()
 
-class CommentDetailsForm(CommentSecurityForm):
+class BaseCommentAbstractForm(CommentSecurityForm):
     """
-    Handles the specific details of the comment (name, comment, etc.).
+    Form for the BaseCommentAbstractModel.
     """
-    name          = forms.CharField(label=_("Name"), max_length=50)
-    email         = forms.EmailField(label=_("Email address"))
-    url           = forms.URLField(label=_("URL"), required=False)
-    comment       = forms.CharField(label=_('Comment'), widget=forms.Textarea,
-                                    max_length=COMMENT_MAX_LENGTH)
-
     def get_comment_object(self):
         """
         Return a new (unsaved) comment object based on the information in this
@@ -107 +101 @@
         """
         if not self.is_valid():
             raise ValueError("get_comment_object may only be called on valid forms")
-        
+
         CommentModel = self.get_comment_model()
         new = CommentModel(**self.get_comment_create_data())
         new = self.check_for_duplicate_comment(new)
-        
+
         return new
-        
+
     def get_comment_model(self):
         """
         Get the comment model to create with this form. Subclasses in custom
         comment apps should override this, get_comment_create_data, and perhaps
         check_for_duplicate_comment to provide custom comment models.
         """
-        return Comment
-        
+        return BaseCommentAbstractModel
+
     def get_comment_create_data(self):
         """
         Returns the dict of data to be used to create a comment. Subclasses in
@@ -131 +125 @@
         return dict(
             content_type = ContentType.objects.get_for_model(self.target_object),
             object_pk    = force_unicode(self.target_object._get_pk_val()),
+            site_id      = settings.SITE_ID,
+        )
+
+    def check_for_duplicate_comment(self, new):
+        """
+        This meant to be overriden in custom form.
+        Do any checks that this comment is not a duplicate here.
+        """
+        return new
+
+class CommentDetailsForm(BaseCommentAbstractForm):
+    """
+    Handles the specific details of the comment (name, comment, etc.).
+    """
+    name          = forms.CharField(label=_("Name"), max_length=50)
+    email         = forms.EmailField(label=_("Email address"))
+    url           = forms.URLField(label=_("URL"), required=False)
+    comment       = forms.CharField(label=_('Comment'), widget=forms.Textarea,
+                                    max_length=COMMENT_MAX_LENGTH)
+
+    def get_comment_model(self):
+        return Comment
+
+    def get_comment_create_data(self):
+        data = super(CommentDetailsForm, self).get_comment_create_data()
+        data.update(dict(
             user_name    = self.cleaned_data["name"],
             user_email   = self.cleaned_data["email"],
             user_url     = self.cleaned_data["url"],
             comment      = self.cleaned_data["comment"],
             submit_date  = datetime.datetime.now(),
-            site_id      = settings.SITE_ID,
             is_public    = True,
             is_removed   = False,
-        )
-        
+        ))
+        return data
+
     def check_for_duplicate_comment(self, new):
         """
         Check that a submitted comment isn't a duplicate. This might be caused
@@ -156 +176 @@
         for old in possible_duplicates:
             if old.submit_date.date() == new.submit_date.date() and old.comment == new.comment:
                 return old
-                
+
         return new
 
     def clean_comment(self):

django/contrib/comments/models.py

@@ -24 +24 @@
     content_object = generic.GenericForeignKey(ct_field="content_type", fk_field="object_pk")
 
     # Metadata about the comment
-    site        = models.ForeignKey(Site)
+    site        = models.ForeignKey(Site) # backward compatibility stuff
 
     class Meta:
         abstract = True

docs/ref/contrib/comments/custom.txt

@@ -69 +69 @@
         title = models.CharField(max_length=300)
     
 All custom comment models must subclass :class:`BaseCommentAbstractModel`.
+Or if you just want to add title field to a comment, extend :class:`Comment`.
 
 Next, we'll define a custom comment form in ``forms.py``. This is a little more
 tricky: we have to both create a form and override
@@ -77 +78 @@
 field::
 
     from django import forms
-    from django.contrib.comments.forms import CommentForm
+    from django.contrib.comments.forms import BaseCommentAbstractForm
     from my_comment_app.models import CommentWithTitle
 
-    class CommentFormWithTitle(CommentForm):
+    class CommentFormWithTitle(BaseCommentAbstractForm):
         title = forms.CharField(max_length=300)
         
         def get_comment_model(self):
@@ -100 +101 @@
 Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
 point Django at these classes we've created::
 
-    from my_comments_app.models import CommentWithTitle
-    from my_comments_app.forms import CommentFormWithTitle
+    from my_comment_app.models import CommentWithTitle
+    from my_comment_app.forms import CommentFormWithTitle
 
     def get_model():
         return CommentWithTitle
@@ -186 +187 @@
     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.
- No newline at end of file
+    to the :func:`django.contrib.comments.views.moderation.approve` view.