diff options
Diffstat (limited to 'parts/django/docs/ref/contrib/comments')
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/custom.txt | 202 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/example.txt | 208 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/forms.txt | 46 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/index.txt | 302 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/models.txt | 80 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/moderation.txt | 230 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/settings.txt | 33 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/signals.txt | 91 | ||||
| -rw-r--r-- | parts/django/docs/ref/contrib/comments/upgrade.txt | 78 |
9 files changed, 0 insertions, 1270 deletions
diff --git a/parts/django/docs/ref/contrib/comments/custom.txt b/parts/django/docs/ref/contrib/comments/custom.txt deleted file mode 100644 index 5411d9c..0000000 --- a/parts/django/docs/ref/contrib/comments/custom.txt +++ /dev/null @@ -1,202 +0,0 @@ -================================== -Customizing the comments framework -================================== - -.. currentmodule:: django.contrib.comments - -If the built-in comment framework doesn't quite fit your needs, you can extend -the comment app's behavior to add custom data and logic. The comments framework -lets you extend the built-in comment model, the built-in comment form, and the -various comment views. - -The :setting:`COMMENTS_APP` setting is where this customization begins. Set -:setting:`COMMENTS_APP` to the name of the app you'd like to use to provide -custom behavior. You'll use the same syntax as you'd use for -:setting:`INSTALLED_APPS`, and the app given must also be in the -:setting:`INSTALLED_APPS` list. - -For example, if you wanted to use an app named ``my_comment_app``, your -settings file would contain:: - - INSTALLED_APPS = [ - ... - 'my_comment_app', - ... - ] - - COMMENTS_APP = 'my_comment_app' - -The app named in :setting:`COMMENTS_APP` provides its custom behavior by -defining some module-level functions in the app's ``__init__.py``. The -:ref:`complete list of these functions <custom-comment-app-api>` can be found -below, but first let's look at a quick example. - -An example custom comments app -============================== - -One of the most common types of customization is modifying the set of fields -provided on the built-in comment model. For example, some sites that allow -comments want the commentator to provide a title for their comment; the built-in -comment model has no field for that title. - -To make this kind of customization, we'll need to do three things: - - #. Create a custom comment :class:`~django.db.models.Model` that adds on the - "title" field. - - #. Create a custom comment :class:`~django.forms.Form` that also adds this - "title" field. - - #. Inform Django of these objects by defining a few functions in a - custom :setting:`COMMENTS_APP`. - -So, carrying on the example above, we're dealing with a typical app structure in -the ``my_custom_app`` directory:: - - my_custom_app/ - __init__.py - models.py - forms.py - -In the ``models.py`` we'll define a ``CommentWithTitle`` model:: - - from django.db import models - from django.contrib.comments.models import Comment - - class CommentWithTitle(Comment): - title = models.CharField(max_length=300) - -Most custom comment models will subclass the :class:`Comment` model. However, -if you want to substantially remove or change the fields available in the -:class:`Comment` model, but don't want to rewrite the templates, you could -try subclassing from :class:`BaseCommentAbstractModel`. - -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 -:meth:`CommentForm.get_comment_model` and -:meth:`CommentForm.get_comment_create_data` to return deal with our custom title -field:: - - from django import forms - from django.contrib.comments.forms import CommentForm - from my_comment_app.models import CommentWithTitle - - class CommentFormWithTitle(CommentForm): - title = forms.CharField(max_length=300) - - def get_comment_model(self): - # Use our custom comment model instead of the built-in one. - return CommentWithTitle - - def get_comment_create_data(self): - # Use the data of the superclass, and add in the title field - data = super(CommentFormWithTitle, self).get_comment_create_data() - data['title'] = self.cleaned_data['title'] - return data - -Django provides a couple of "helper" classes to make writing certain types of -custom comment forms easier; see :mod:`django.contrib.comments.forms` for -more. - -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 - - def get_model(): - return CommentWithTitle - - def get_form(): - return CommentFormWithTitle - - -.. warning:: - - Be careful not to create cyclic imports in your custom comments app. - If you feel your comment configuration isn't being used as defined -- - for example, if your comment moderation policy isn't being applied -- - you may have a cyclic import problem. - - If you are having unexplained problems with comments behavior, check - if your custom comments application imports (even indirectly) - any module that itself imports Django's comments module. - -The above process should take care of most common situations. For more -advanced usage, there are additional methods you can define. Those are -explained in the next section. - -.. _custom-comment-app-api: - -Custom comment app API -====================== - -The :mod:`django.contrib.comments` app defines the following methods; any -custom comment app must define at least one of them. All are optional, -however. - -.. 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 ``<form 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. diff --git a/parts/django/docs/ref/contrib/comments/example.txt b/parts/django/docs/ref/contrib/comments/example.txt deleted file mode 100644 index 424bdb1..0000000 --- a/parts/django/docs/ref/contrib/comments/example.txt +++ /dev/null @@ -1,208 +0,0 @@ -.. highlightlang:: html+django - -=========================================== -Example of using the in-built comments app -=========================================== - -Follow the first three steps of the quick start guide in the -:doc:`documentation </ref/contrib/comments/index>`. - -Now suppose, you have an app (``blog``) with a model (``Post``) -to which you want to attach comments. Let us also suppose that -you have a template called ``blog_detail.html`` where you want -to display the comments list and comment form. - -Template -======== - -First, we should load the ``comment`` template tags in the -``blog_detail.html`` so that we can use it's functionality. So -just like all other custom template tag libraries:: - - {% load comments %} - -Next, let us add the number of comments attached to the particular -model instance of ``Post``. For this we assume that a context -variable ``object_pk`` is present which gives the ``id`` of the -instance of ``Post``. - -The usage of the :ttag:`get_comment_count` tag is like below:: - - {% get_comment_count for blog.post object_pk as comment_count %} - <p>{{ comment_count }} comments have been posted.</p> - -If you have the instance (say ``entry``) of the model (``Post``) -available in the context, then you can refer to it directly:: - - {% get_comment_count for entry as comment_count %} - <p>{{ comment_count }} comments have been posted.</p> - -.. versionadded:: 1.2 - -Next, we can use the :ttag:`render_comment_list` tag, to render all comments -to the given instance (``entry``) by using the ``comments/list.html`` template. - - {% render_comment_list for entry %} - -Django will will look for the ``list.html`` under the following directories -(for our example):: - - comments/blog/post/list.html - comments/blog/list.html - comments/list.html - -To get a list of comments, we make use of the :ttag:`get_comment_list` tag. -This tag's usage is very similar to the :ttag:`get_comment_count` tag. We -need to remember that the :ttag:`get_comment_list` returns a list of comments -and hence we will have to iterate through them to display them:: - - {% get_comment_list for blog.post object_pk as comment_list %} - {% for comment in comment_list %} - <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p> - ... - <p>Comment: {{ comment.comment }}</p> - ... - {% endfor %} - -Finally, we display the comment form, enabling users to enter their -comments. There are two ways of doing so. The first is when you want to -display the comments template available under your ``comments/form.html``. -The other method gives you a chance to customize the form. - -The first method makes use of the :ttag:`render_comment_form` tag. It's usage -too is similar to the other three tags we have discussed above:: - - {% render_comment_form for entry %} - -It looks for the ``form.html`` under the following directories -(for our example):: - - comments/blog/post/form.html - comments/blog/form.html - comments/form.html - -Since we customize the form in the second method, we make use of another -tag called :ttag:`comment_form_target`. This tag on rendering gives the URL -where the comment form is posted. Without any :doc:`customization -</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to -``/comments/post/``. We use this tag in the form's ``action`` attribute. - -The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by -creating a context variable. One can iterate over the ``form`` object to -get individual fields. This gives you fine-grain control over the form:: - - {% for field in form %} - {% ifequal field.name "comment" %} - <!-- Customize the "comment" field, say, make CSS changes --> - ... - {% endfor %} - -But let's look at a simple example:: - - {% get_comment_form for entry as form %} - <!-- A context variable called form is created with the necessary hidden - fields, timestamps and security hashes --> - <table> - <form action="{% comment_form_target %}" method="post"> - {{ form }} - <tr> - <td></td> - <td><input type="submit" name="preview" class="submit-post" value="Preview"></td> - </tr> - </form> - </table> - -Flagging -======== - -If you want your users to be able to flag comments (say for profanity), you -can just direct them (by placing a link in your comment list) to ``/flag/{{ -comment.id }}/``. Similarly, a user with requisite permissions (``"Can -moderate comments"``) can approve and delete comments. This can also be -done through the ``admin`` as you'll see later. You might also want to -customize the following templates: - - * ``flag.html`` - * ``flagged.html`` - * ``approve.html`` - * ``approved.html`` - * ``delete.html`` - * ``deleted.html`` - -found under the directory structure we saw for ``form.html``. - -Feeds -===== - -Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the -latest comments, you can use the in-built :class:`LatestCommentFeed`. Just -enable it in your project's ``urls.py``: - -.. code-block:: python - - from django.conf.urls.defaults import * - from django.contrib.comments.feeds import LatestCommentFeed - - feeds = { - 'latest': LatestCommentFeed, - } - - urlpatterns = patterns('', - # ... - (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', - {'feed_dict': feeds}), - # ... - ) - -Now you should have the latest comment feeds being served off ``/feeds/latest/``. - -Moderation -========== - -Now that we have the comments framework working, we might want to have some -moderation setup to administer the comments. The comments framework comes -in-built with :doc:`generic comment moderation -</ref/contrib/comments/moderation>`. The comment moderation has the following -features (all of which or only certain can be enabled): - - * Enable comments for a particular model instance. - * Close comments after a particular (user-defined) number of days. - * Email new comments to the site-staff. - -To enable comment moderation, we subclass the :class:`CommentModerator` and -register it with the moderation features we want. Let us suppose we want to -close comments after 7 days of posting and also send out an email to the -site staff. In ``blog/models.py``, we register a comment moderator in the -following way: - -.. code-block:: python - - from django.contrib.comments.moderation import CommentModerator, moderator - from django.db import models - - class Post(models.Model): - title = models.CharField(max_length = 255) - content = models.TextField() - posted_date = models.DateTimeField() - - class PostModerator(CommentModerator): - email_notification = True - auto_close_field = 'posted_date' - # Close the comments after 7 days. - close_after = 7 - - moderator.register(Post, PostModerator) - -The generic comment moderation also has the facility to remove comments. -These comments can then be moderated by any user who has access to the -``admin`` site and the ``Can moderate comments`` permission (can be set -under the ``Users`` page in the ``admin``). - -The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the -``Action`` drop-down in the ``admin`` under the ``Comments`` page. - -.. note:: - - Only a super-user will be able to delete comments from the database. - ``Remove Comments`` only sets the ``is_public`` attribute to - ``False``. diff --git a/parts/django/docs/ref/contrib/comments/forms.txt b/parts/django/docs/ref/contrib/comments/forms.txt deleted file mode 100644 index c21a27b..0000000 --- a/parts/django/docs/ref/contrib/comments/forms.txt +++ /dev/null @@ -1,46 +0,0 @@ -==================== -Comment form classes -==================== - -.. module:: django.contrib.comments.forms - :synopsis: Forms for dealing with the built-in comment model. - -The ``django.contrib.comments.forms`` module contains a handful of forms -you'll use when writing custom views dealing with comments, or when writing -:doc:`custom comment apps </ref/contrib/comments/custom>`. - -.. class:: CommentForm - - The main comment form representing the standard, built-in way of handling - submitted comments. This is the class used by all the views - :mod:`django.contrib.comments` to handle submitted comments. - - If you want to build custom views that are similar to Django's built-in - comment handling views, you'll probably want to use this form. - -Abstract comment forms for custom comment apps ----------------------------------------------- - -If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`, -you might want to replace *some* of the form logic but still rely on parts of -the existing form. - -:class:`CommentForm` is actually composed of a couple of abstract base class -forms that you can subclass to reuse pieces of the form handling logic: - -.. class:: CommentSecurityForm - - Handles the anti-spoofing protection aspects of the comment form handling. - - This class contains the ``content_type`` and ``object_pk`` fields pointing - to the object the comment is attached to, along with a ``timestamp`` and a - ``security_hash`` of all the form data. Together, the timestamp and the - security hash ensure that spammers can't "replay" form submissions and - flood you with comments. - -.. class:: CommentDetailsForm - - Handles the details of the comment itself. - - This class contains the ``name``, ``email``, ``url``, and the ``comment`` - field itself, along with the associated validation logic.
\ No newline at end of file diff --git a/parts/django/docs/ref/contrib/comments/index.txt b/parts/django/docs/ref/contrib/comments/index.txt deleted file mode 100644 index 817871e..0000000 --- a/parts/django/docs/ref/contrib/comments/index.txt +++ /dev/null @@ -1,302 +0,0 @@ -=========================== -Django's comments framework -=========================== - -.. module:: django.contrib.comments - :synopsis: Django's comment framework - -.. highlightlang:: html+django - -Django includes a simple, yet customizable comments framework. The built-in -comments framework can be used to attach comments to any model, so you can use -it for comments on blog entries, photos, book chapters, or anything else. - -.. note:: - - If you used to use Django's older (undocumented) comments framework, you'll - need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>` - for instructions. - -Quick start guide -================= - -To get started using the ``comments`` app, follow these steps: - - #. Install the comments framework by adding ``'django.contrib.comments'`` to - :setting:`INSTALLED_APPS`. - - #. Run ``manage.py syncdb`` so that Django will create the comment tables. - - #. Add the comment app's URLs to your project's ``urls.py``: - - .. code-block:: python - - urlpatterns = patterns('', - ... - (r'^comments/', include('django.contrib.comments.urls')), - ... - ) - - #. Use the `comment template tags`_ below to embed comments in your - templates. - -You might also want to examine :doc:`/ref/contrib/comments/settings`. - -Comment template tags -===================== - -You'll primarily interact with the comment system through a series of template -tags that let you embed comments and generate forms for your users to post them. - -Like all custom template tag libraries, you'll need to :ref:`load the custom -tags <loading-custom-template-libraries>` before you can use them:: - - {% load comments %} - -Once loaded you can use the template tags below. - -Specifying which object comments are attached to ------------------------------------------------- - -Django's comments are all "attached" to some parent object. This can be any -instance of a Django model. Each of the tags below gives you a couple of -different ways you can specify which object to attach to: - - #. Refer to the object directly -- the more common method. Most of the - time, you'll have some object in the template's context you want - to attach the comment to; you can simply use that object. - - For example, in a blog entry page that has a variable named ``entry``, - you could use the following to load the number of comments:: - - {% get_comment_count for entry as comment_count %}. - - #. Refer to the object by content-type and object id. You'd use this method - if you, for some reason, don't actually have direct access to the object. - - Following the above example, if you knew the object ID was ``14`` but - didn't have access to the actual object, you could do something like:: - - {% get_comment_count for blog.entry 14 as comment_count %} - - In the above, ``blog.entry`` is the app label and (lower-cased) model - name of the model class. - -Displaying comments -------------------- - -To display a list of comments, you can use the template tags -:ttag:`render_comment_list` or :ttag:`get_comment_list`. - -.. templatetag:: render_comment_list - -Quickly rendering a comment list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The easiest way to display a list of comments for some object is by using -:ttag:`render_comment_list`:: - - {% render_comment_list for [object] %} - -For example:: - - {% render_comment_list for event %} - -This will render comments using a template named ``comments/list.html``, a -default version of which is included with Django. - -.. templatetag:: get_comment_list - -Rendering a custom comment list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To get the list of comments for some object, use :ttag:`get_comment_list`:: - - {% get_comment_list for [object] as [varname] %} - -For example:: - - {% get_comment_list for event as comment_list %} - {% for comment in comment_list %} - ... - {% endfor %} - -This returns a list of :class:`~django.contrib.comments.models.Comment` objects; -see :doc:`the comment model documentation </ref/contrib/comments/models>` for -details. - -.. templatetag:: get_comment_permalink - -Linking to comments -------------------- - -.. versionadded:: 1.2 - -To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`:: - - {% get_comment_permalink comment_obj [format_string] %} - -By default, the named anchor that will be appended to the URL will be the letter -'c' followed by the comment id, for example 'c82'. You may specify a custom -format string if you wish to override this behavior:: - - {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%} - -The format string is a standard python format string. Valid mapping keys -include any attributes of the comment object. - -Regardless of whether you specify a custom anchor pattern, you must supply a -matching named anchor at a suitable place in your template. - -For example:: - - {% for comment in comment_list %} - <a name="c{{ comment.id }}"></a> - <a href="{% get_comment_permalink comment %}"> - permalink for comment #{{ forloop.counter }} - </a> - ... - {% endfor %} - -.. warning:: - - There's a known bug in Safari/Webkit which causes the named anchor to be - forgotten following a redirect. The practical impact for comments is that - the Safari/webkit browsers will arrive at the correct page but will not - scroll to the named anchor. - -.. templatetag:: get_comment_count - -Counting comments ------------------ - -To count comments attached to an object, use :ttag:`get_comment_count`:: - - {% get_comment_count for [object] as [varname] %} - -For example:: - - {% get_comment_count for event as comment_count %} - - <p>This event has {{ comment_count }} comments.</p> - - -Displaying the comment post form --------------------------------- - -To show the form that users will use to post a comment, you can use -:ttag:`render_comment_form` or :ttag:`get_comment_form` - -.. templatetag:: render_comment_form - -Quickly rendering the comment form -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The easiest way to display a comment form is by using -:ttag:`render_comment_form`:: - - {% render_comment_form for [object] %} - -For example:: - - {% render_comment_form for event %} - -This will render comments using a template named ``comments/form.html``, a -default version of which is included with Django. - -.. templatetag:: get_comment_form - -Rendering a custom comment form -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want more control over the look and feel of the comment form, you use use -:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that -you can use in the template:: - - {% get_comment_form for [object] as [varname] %} - -A complete form might look like:: - - {% get_comment_form for event as form %} - <form action="{% comment_form_target %}" method="post"> - {{ form }} - <tr> - <td></td> - <td><input type="submit" name="preview" class="submit-post" value="Preview"></td> - </tr> - </form> - -Be sure to read the `notes on the comment form`_, below, for some special -considerations you'll need to make if you're using this approach. - -.. templatetag:: comment_form_target - -Getting the comment form target -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You may have noticed that the above example uses another template tag -- -:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the -form. This will always return the correct URL that comments should be posted to; -you'll always want to use it like above:: - - <form action="{% comment_form_target %}" method="post"> - -Redirecting after the comment post -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To specify the URL you want to redirect to after the comment has been posted, -you can include a hidden form input called ``next`` in your comment form. For example:: - - <input type="hidden" name="next" value="{% url my_comment_was_posted %}" /> - -.. _notes-on-the-comment-form: - -Notes on the comment form -------------------------- - -The form used by the comment system has a few important anti-spam attributes you -should know about: - - * It contains a number of hidden fields that contain timestamps, information - about the object the comment should be attached to, and a "security hash" - used to validate this information. If someone tampers with this data -- - something comment spammers will try -- the comment submission will fail. - - If you're rendering a custom comment form, you'll need to make sure to - pass these values through unchanged. - - * The timestamp is used to ensure that "reply attacks" can't continue very - long. Users who wait too long between requesting the form and posting a - comment will have their submissions refused. - - * The comment form includes a "honeypot_" field. It's a trap: if any data is - entered in that field, the comment will be considered spam (spammers often - automatically fill in all fields in an attempt to make valid submissions). - - The default form hides this field with a piece of CSS and further labels - it with a warning field; if you use the comment form with a custom - template you should be sure to do the same. - -The comments app also depends on the more general :doc:`Cross Site Request -Forgery protection </ref/contrib/csrf>` that comes with Django. As described in -the documentation, it is best to use ``CsrfViewMiddleware``. However, if you -are not using that, you will need to use the ``csrf_protect`` decorator on any -views that include the comment form, in order for those views to be able to -output the CSRF token and cookie. - -.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing) - -More information -================ - -.. toctree:: - :maxdepth: 1 - - models - settings - signals - upgrade - custom - forms - moderation - example diff --git a/parts/django/docs/ref/contrib/comments/models.txt b/parts/django/docs/ref/contrib/comments/models.txt deleted file mode 100644 index e773790..0000000 --- a/parts/django/docs/ref/contrib/comments/models.txt +++ /dev/null @@ -1,80 +0,0 @@ -=========================== -The built-in comment models -=========================== - -.. module:: django.contrib.comments.models - :synopsis: The built-in comment models - -.. class:: Comment - - Django's built-in comment model. Has the following fields: - - .. attribute:: content_object - - A :class:`~django.contrib.contettypes.generic.GenericForeignKey` - attribute pointing to the object the comment is attached to. You can use - this to get at the related object (i.e. ``my_comment.content_object``). - - Since this field is a - :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's - actually syntactic sugar on top of two underlying attributes, described - below. - - .. attribute:: content_type - - A :class:`~django.db.models.ForeignKey` to - :class:`~django.contrib.contenttypes.models.ContentType`; this is the - type of the object the comment is attached to. - - .. attribute:: object_pk - - A :class:`~django.db.models.TextField` containing the primary - key of the object the comment is attached to. - - .. attribute:: site - - A :class:`~django.db.models.ForeignKey` to the - :class:`~django.contrib.sites.models.Site` on which the comment was - posted. - - .. attribute:: user - - A :class:`~django.db.models.ForeignKey` to the - :class:`~django.contrib.auth.models.User` who posted the comment. - May be blank if the comment was posted by an unauthenticated user. - - .. attribute:: user_name - - The name of the user who posted the comment. - - .. attribute:: user_email - - The email of the user who posted the comment. - - .. attribute:: user_url - - The URL entered by the person who posted the comment. - - .. attribute:: comment - - The actual content of the comment itself. - - .. attribute:: submit_date - - The date the comment was submitted. - - .. attribute:: ip_address - - The IP address of the user posting the comment. - - .. attribute:: is_public - - ``False`` if the comment is in moderation (see - :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will - be displayed on the site. - - .. attribute:: is_removed - - ``True`` if the comment was removed. Used to keep track of removed - comments instead of just deleting them. - diff --git a/parts/django/docs/ref/contrib/comments/moderation.txt b/parts/django/docs/ref/contrib/comments/moderation.txt deleted file mode 100644 index 519bc5e..0000000 --- a/parts/django/docs/ref/contrib/comments/moderation.txt +++ /dev/null @@ -1,230 +0,0 @@ -========================== -Generic comment moderation -========================== - -.. module:: django.contrib.comments.moderation - :synopsis: Support for automatic comment moderation. - -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. - - -Overview -======== - -The entire system is contained within ``django.contrib.comments.moderation``, -and uses a two-step process to enable moderation for any given model: - -1. A subclass of :class:`CommentModerator` - is defined which specifies the moderation options the model wants to - enable. - -2. The model is registered with the moderation system, passing in the - model class and the class which specifies its moderation options. - -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``: - -1. If the ``Entry``'s ``enable_comments`` field is ``False``, the - comment will simply be disallowed (i.e., immediately deleted). - -2. If the ``enable_comments`` field is ``True``, the comment will be - allowed to save. - -3. Once the comment is saved, an email should be sent to site staff - notifying them of the new comment. - -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 :class:`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. - -Built-in moderation options ---------------------------- - -.. class:: CommentModerator - - Most common comment-moderation needs can be handled by subclassing - :class:`CommentModerator` and - changing the values of pre-defined attributes; the full range of built-in - options is as follows. - - .. attribute:: auto_close_field - - If this is set to the name of a - :class:`~django.db.models.fields.DateField` or - :class:`~django.db.models.fields.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 :attr:`close_after`, which specifies the - number of days past which comments should be - disallowed. Default value is ``None``. - - .. attribute:: auto_moderate_field - - Like :attr:`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 - :attr:`moderate_after`, which specifies the number of days past - which comments should be moderated. Default value is ``None``. - - .. attribute:: close_after - - If :attr:`auto_close_field` is used, this must specify the number - of days past the value of the field specified by - :attr:`auto_close_field` after which new comments for an object - should be disallowed. Default value is ``None``. - - .. attribute:: 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``. - - .. attribute:: enable_field - - If this is set to the name of a - :class:`~django.db.models.fields.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``. - - .. attribute:: moderate_after - - If :attr:`auto_moderate_field` is used, this must specify the number - of days past the value of the field specified by - :attr:`auto_moderate_field` after which new comments for an object - should be marked non-public. Default value is ``None``. - -Simply subclassing :class:`CommentModerator` and changing the values of these -options will automatically enable the various moderation methods for any -models registered using the subclass. - -Adding custom moderation methods --------------------------------- - -For situations where the built-in options listed above are not -sufficient, subclasses of :class:`CommentModerator` can also override -the methods which actually perform the moderation, and apply any logic -they desire. :class:`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 -:class:`~django.http.HttpRequest` in which the comment is being submitted: - -.. method:: 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). - -.. method:: 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. - -.. method:: 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). - - -Registering models for moderation ---------------------------------- - -The moderation system, represented by -``django.contrib.comments.moderation.moderator`` is an instance of the class -:class:`Moderator`, which allows registration and "unregistration" of models -via two methods: - -.. function:: 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 - :exc:`AlreadyModerated` will be raised. - -.. function:: 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 - :exc:`NotModerated` will be raised. - - -Customizing the moderation system ---------------------------------- - -Most use cases will work easily with simple subclassing of -:class:`CommentModerator` and registration with the provided -:class:`Moderator` instance, but customization of global moderation behavior -can be achieved by subclassing :class:`Moderator` and instead registering -models with an instance of the subclass. - -.. class:: Moderator - - In addition to the :meth:`Moderator.register` and - :meth:`Moderator.unregister` methods detailed above, the following methods - on :class:`Moderator` can be overridden to achieve customized behavior: - - .. method:: connect - - Determines how moderation is set up globally. The base - implementation in - :class:`Moderator` does this by - attaching listeners to the :data:`~django.contrib.comments.signals.comment_will_be_posted` - and :data:`~django.contrib.comments.signals.comment_was_posted` signals from the - comment models. - - .. method:: 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). - - .. method:: 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). diff --git a/parts/django/docs/ref/contrib/comments/settings.txt b/parts/django/docs/ref/contrib/comments/settings.txt deleted file mode 100644 index 1f1aeca..0000000 --- a/parts/django/docs/ref/contrib/comments/settings.txt +++ /dev/null @@ -1,33 +0,0 @@ -================ -Comment settings -================ - -These settings configure the behavior of the comments framework: - -.. setting:: COMMENTS_HIDE_REMOVED - -COMMENTS_HIDE_REMOVED ---------------------- - -If ``True`` (default), removed comments will be excluded from comment -lists/counts (as taken from template tags). Otherwise, the template author is -responsible for some sort of a "this comment has been removed by the site staff" -message. - -.. setting:: COMMENT_MAX_LENGTH - -COMMENT_MAX_LENGTH ------------------- - -The maximum length of the comment field, in characters. Comments longer than -this will be rejected. Defaults to 3000. - -.. setting:: COMMENTS_APP - -COMMENTS_APP ------------- - -An app which provides :doc:`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`. diff --git a/parts/django/docs/ref/contrib/comments/signals.txt b/parts/django/docs/ref/contrib/comments/signals.txt deleted file mode 100644 index 7ae34a1..0000000 --- a/parts/django/docs/ref/contrib/comments/signals.txt +++ /dev/null @@ -1,91 +0,0 @@ -================================ -Signals sent by the comments app -================================ - -.. module:: django.contrib.comments.signals - :synopsis: Signals sent by the comment module. - -The comment app sends a series of :doc:`signals </topics/signals>` to allow for -comment moderation and similar activities. See :doc:`the introduction to signals -</topics/signals>` for information about how to register for and receive these -signals. - -comment_will_be_posted -====================== - -.. data:: django.contrib.comments.signals.comment_will_be_posted - :module: - -Sent just before a comment will be saved, after it's been sanity checked and -submitted. This can be used to modify the comment (in place) with posting -details or other such actions. - -If any receiver returns ``False`` the comment will be discarded and a 403 (not -allowed) response will be returned. - -This signal is sent at more or less the same time (just before, actually) as the -``Comment`` object's :data:`~django.db.models.signals.pre_save` signal. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance about to be posted. Note that it won't have been - saved into the database yet, so it won't have a primary key, and any - relations might not work correctly yet. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. - -comment_was_posted -================== - -.. data:: django.contrib.comments.signals.comment_was_posted - :module: - -Sent just after the comment is saved. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. - -comment_was_flagged -=================== - -.. data:: django.contrib.comments.signals.comment_was_flagged - :module: - -Sent after a comment was "flagged" in some way. Check the flag to see if this -was a user requesting removal of a comment, a moderator approving/removing a -comment, or some other custom user flag. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``flag`` - The :class:`~django.contrib.comments.models.CommentFlag` that's been - attached to the comment. - - ``created`` - ``True`` if this is a new flag; ``False`` if it's a duplicate flag. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. diff --git a/parts/django/docs/ref/contrib/comments/upgrade.txt b/parts/django/docs/ref/contrib/comments/upgrade.txt deleted file mode 100644 index 3d6b5af..0000000 --- a/parts/django/docs/ref/contrib/comments/upgrade.txt +++ /dev/null @@ -1,78 +0,0 @@ -=============================================== -Upgrading from Django's previous comment system -=============================================== - -Prior versions of Django included an outdated, undocumented comment system. Users who reverse-engineered this framework will need to upgrade to use the -new comment system; this guide explains how. - -The main changes from the old system are: - - * This new system is documented. - - * It uses modern Django features like :doc:`forms </topics/forms/index>` and - :doc:`modelforms </topics/forms/modelforms>`. - - * It has a single ``Comment`` model instead of separate ``FreeComment`` and - ``Comment`` models. - - * Comments have "email" and "URL" fields. - - * No ratings, photos and karma. This should only effect World Online. - - * The ``{% comment_form %}`` tag no longer exists. Instead, there's now two - functions: ``{% get_comment_form %}``, which returns a form for posting a - new comment, and ``{% render_comment_form %}``, which renders said form - using the ``comments/form.html`` template. - - * The way comments are include in your URLconf have changed; you'll need to - replace:: - - (r'^comments/', include('django.contrib.comments.urls.comments')), - - with:: - - (r'^comments/', include('django.contrib.comments.urls')), - -Upgrading data --------------- - -The data models for Django's comment system have changed, as have the -table names. Before you transfer your existing data into the new comments -system, make sure that you have installed the new comments system as -explained in the -:doc:`quick start guide </ref/contrib/comments/index>`. -This will ensure that the new tables have been properly created. - -To transfer your data into the new comments system, you'll need to directly -run the following SQL: - -.. code-block:: sql - - BEGIN; - - INSERT INTO django_comments - (content_type_id, object_pk, site_id, user_name, user_email, user_url, - comment, submit_date, ip_address, is_public, is_removed) - SELECT - content_type_id, object_id, site_id, person_name, '', '', comment, - submit_date, ip_address, is_public, not approved - FROM comments_freecomment; - - INSERT INTO django_comments - (content_type_id, object_pk, site_id, user_id, user_name, user_email, - user_url, comment, submit_date, ip_address, is_public, is_removed) - SELECT - content_type_id, object_id, site_id, user_id, '', '', '', comment, - submit_date, ip_address, is_public, is_removed - FROM comments_comment; - - UPDATE django_comments SET user_name = ( - SELECT username FROM auth_user - WHERE django_comments.user_id = auth_user.id - ) WHERE django_comments.user_id is not NULL; - UPDATE django_comments SET user_email = ( - SELECT email FROM auth_user - WHERE django_comments.user_id = auth_user.id - ) WHERE django_comments.user_id is not NULL; - - COMMIT; |