Cleanup, example and overall improvements to django-threadedcomments

.gitignore

@@ -7,3 +7,4 @@
 .pydevproject
 .settings
 *.swp
+.idea/

CHANGELOG.txt

@@ -1,3 +1,9 @@
+Version 0.9, dev.
+-----------------
+
+Rewrote application to use django.contrib.comments
+Included example app
+
 Version 0.5.1, 31st March 2009
 ------------------------------
 

README.rst

@@ -0,0 +1,159 @@
+django-threadedcomments
+=======================
+
+*threadedcomments* is a Django application which allows for the simple creation of a threaded commenting system.
+Commenters can reply both to the original item, and reply to other comments as well.
+
+The application is (as of 0.9) built on top of django.contrib.comments,
+which allows it to be easily extended by other modules.
+
+
+Installation
+============
+
+Download this Git repository, and install it::
+
+    cd django-threadedcomments
+    pip install .
+
+It's preferred to install the module in a virtual environment.
+
+Configuration
+-------------
+
+Add the following to ``settings.py``::
+
+    INSTALLED_APPS += (
+        'threadedcomments',
+        'django.contrib.comments',
+    )
+
+    COMMENTS_APP = 'threadedcomments'
+
+By placing the ``threadedcomments`` app above the ``django.contrib.comments`` application,
+the placeholder ``comments/list.html`` template will already be replaced by a threaded view.
+
+Make sure django.contrib.comments_ is configured in ``urls.py``::
+
+    urlpatterns += patterns('',
+        url(r'^articles/comments/', include('django.contrib.comments.urls')),
+    )
+
+Provide a template that displays the comments for the ``object`` (e.g. article or blog entry)::
+
+    {% load threadedcomments_tags %}
+
+    ...
+
+    <h2>Comments for {{ object.title }}:</h2>
+
+    {% render_comment_list for object %}
+    {% render_comment_form for object %}
+
+
+Template design
+---------------
+
+Naturally, it's desirable to write your own version of ``comments/list.html`` in your project,
+or use one of the ``comments/app/list.html`` or ``comments/app/model/list.html`` overrides.
+
+Make sure to override ``comments/base.html`` as well, so the other views of django.contrib.comments_
+are displayed using your web site design. The other templates of django.contrib.comments_ are
+very plain as well on purpose (for example ``comments/posted.html``),
+since these pages depend on the custom design of the web site.
+
+See the provided ``example`` app for a basic configuration,
+including a JavaScript-based reply form that moves to the comment the visitor replies to.
+
+
+Template tags
+=============
+
+The ``threadedcomments_tags`` library is a drop-in replacement for the ``comments`` library
+that is required for the plain comments. The tags are forwards compatible;
+they support the same syntax as django.contrib.comments_ provides,
+and they add a few extra parameters.
+
+Fething comment counts::
+
+    {% get_comment_count for [object] as [varname] %}
+    {% get_comment_count for [object] as [varname] root_only %}
+
+    {% get_comment_count for [app].[model] [id] as [varname] %}
+    {% get_comment_count for [app].[model] [id] as [varname] root_only %}
+
+Fetching the comments list::
+
+    {% get_comment_list for [object] as [varname] %}
+    {% get_comment_list for [object] as [varname] flat %}
+    {% get_comment_list for [object] as [varname] root_only %}
+
+Rendering the comments list::
+
+    {% render_comment_list for [object] %}
+    {% render_comment_list for [object] root_only %}
+
+    {% render_comment_list for [app].[model] [id] %}
+    {% render_comment_list for [app].[model] [id] root_only %}
+
+Fetching the comment form::
+
+    {% get_comment_form for [object] as [varname] %}
+    {% get_comment_form for [object] as [varname] with [parent_id] %}
+    {% get_comment_form for [app].[model] [id] as [varname] %}
+    {% get_comment_form for [app].[model] [id] as [varname] with [parent_id] %}
+
+Rendering the comment form::
+
+    {% render_comment_form for [object] %}
+    {% render_comment_form for [object] with [parent_id] %}
+    {% render_comment_form for [app].[model] [id] %}
+    {% render_comment_form for [app].[model] [id] with [parent_id] %}
+
+Rendering the whole tree::
+
+    {% for comment in comment_list|fill_tree|annotate_tree %}
+        {% ifchanged comment.parent_id %}{% else %}</li>{% endifchanged %}
+        {% if not comment.open and not comment.close %}</li>{% endif %}
+        {% if comment.open %}<ul>{% endif %}
+
+        <li id="c{{ comment.id }}">
+            ...
+        {% for close in comment.close %}</li></ul>{% endfor %}
+    {% endfor %}
+
+The ``fill_tree`` filter is required for pagination, it ensures that the parents of the first comment are included as well.
+
+The ``annotate_tree`` filter adds the ``open`` and ``close`` properties to the comment.
+
+
+Extending the module
+====================
+
+The application is built on top of the standard django.contrib.comments_ framework,
+which supports various signals, and template overrides to customize the comments.
+
+To customize django-threadedcomments, override the proper templates, or include the apps that provide the missing features.
+Front-end editing support for example, is left out on purpose. It belongs to the domain of moderation, and policies
+to know "who can do what". That deserves to be in a separate application, it shouldn't be in this application as it focuses on threading.
+The same applies to social media logins, comment subscriptions, spam protection and Ajax posting.
+
+Note that the standard framework also supports moderation, flagging, and RSS feeds too. More documentation can be found at:
+
+* `Django's comments framework <https://docs.djangoproject.com/en/dev/ref/contrib/comments/>`_
+* `Customizing the comments framework <http://docs.djangoproject.com/en/dev/ref/contrib/comments/custom/>`_
+* `Example of using the in-built comments app <http://docs.djangoproject.com/en/dev/ref/contrib/comments/example/>`_
+
+Some of the modules worth looking at are:
+
+* django-comments-spamfighter_
+* django-myrecaptcha_
+* django-fluent-comments_
+
+These modules can enhance the comments system even further.
+
+
+.. _django.contrib.comments: https://docs.djangoproject.com/en/dev/ref/contrib/comments/
+.. _django-fluent-comments: https://github.com/edoburu/django-fluent-comments/
+.. _django-myrecaptcha: https://bitbucket.org/pelletier/django-myrecaptcha/
+.. _django-comments-spamfighter: https://github.com/bartTC/django-comments-spamfighter/

docs/index.txt

@@ -48,7 +48,7 @@ Templates
 
 To use ``threadedcomments`` in templates first initialize the tag library::
 
-    {% load threadedcommentstags %}
+    {% load threadedcomments_tags %}
 
 Then you can use the template tags supplied by the application. The
 templatetags have the same syntax and semantics as the built-in comments

examples/example/core/admin.py

@@ -0,0 +1,8 @@
+from django.contrib import admin
+from core.models import Message
+
+
+class MessageAdmin(admin.ModelAdmin):
+    list_display = ('title', 'text',)
+
+admin.site.register(Message, MessageAdmin)

examples/example/core/models.py

@@ -0,0 +1,16 @@
+from django.core.urlresolvers import reverse
+from django.db import models
+
+class Message(models.Model):
+    title   = models.CharField(max_length=140)
+    text    = models.TextField()
+
+    class Meta:
+        verbose_name = "message"
+        verbose_name_plural = "messages"
+
+    def __unicode__(self):
+        return self.title
+
+    def get_absolute_url(self):
+        return reverse('message_detail', args=(self.pk,))

examples/example/core/templates/comments/base.html

@@ -0,0 +1,19 @@
+{% extends "core/base.html" %}{% load i18n %}
+{% comment %}
+
+  To implement django.contrib.comments in your web site,
+  it is recommended to override the following templates in your app:
+
+     comments/base.html    - map the blocks 'title' and 'contents' to your base template.
+     comments/posted.html  - provide a decent redirect back to the article.
+
+  Other templates could also be overwritten off course, but these two are the basic ones.
+  Features such as editing posts, spam protection, recaptcha, twitter/facebook/openid login etc..
+  are all subject to different applications which can add those features.
+  They don't belong in django-threadedcomments, and hence are not demonstrated here.
+
+{% endcomment %}
+
+{% block head_title %}{% block title %}{% trans "Responses for page" %}{% endblock %}{% endblock %}
+
+{# 'content' block is already defined in the base class, no need to redefine it here. #}

examples/example/core/templates/comments/core/form.html

@@ -0,0 +1,10 @@
+<div id="form-comment">
+    <form action="/comments/post/" method="post">{% csrf_token %}
+        {{ form.as_p }}{# just to keep the example simple. Consider using django-crispy-forms in real life #}
+
+        <p>
+            <input type="submit" value="Submit Comment"/>
+            <a href="#c0" id="cancel_reply">cancel reply</a>
+        </p>
+    </form>
+</div>

examples/example/core/templates/comments/core/list.html

@@ -0,0 +1,26 @@
+{% load threadedcomments_tags %}
+
+<div class="comments_length">
+    <p>{{ comment_list|length }} Comments</p>
+</div>
+
+<div class="comments">
+    {% for comment in comment_list|fill_tree|annotate_tree %}{% ifchanged comment.parent_id %}{% else %}</li>{% endifchanged %}{% if not comment.open and not comment.close %}</li>{% endif %}{% if comment.open %}
+    <ul>{% endif %}
+        <li class="comment_li" id="c{{ comment.id }}">{# c## is used by the absolute URL of the Comment model, so keep that as it is. #}
+            <div class="comment">
+                <div class="comment_info">
+                    <div class="comment_user">{{ comment.user_name }}</div>
+                    <div class="comment_data">
+                        {{ comment.submit_date|date:"d M Y, H:i" }}
+                        | <a href="#c{{ comment.id }}" data-comment-id="{{ comment.id }}" class="comment_reply_link">Reply</a>
+                    </div>
+                </div>
+                <div class="comment_text">
+                    {{ comment.comment }}
+                </div>
+            </div>
+            {% for close in comment.close %}</li></ul>{% endfor %}
+
+    {% endfor %}
+</div>

examples/example/core/templates/comments/posted.html

@@ -0,0 +1,20 @@
+{% extends "comments/base.html" %}{% load i18n %}
+
+{% block title %}{% trans "Thanks for commenting" %}{% endblock %}
+
+{% block extrahead %}
+{{ block.super }}
+    <meta http-equiv="Refresh" content="5; url={{ comment.content_object.get_absolute_url }}#c{{ comment.id }}" />
+{% endblock %}
+
+{% block content %}
+    <h2>{% trans "Thanks for posting your comment" %}</h2>
+    <p>
+      {% blocktrans %}
+      We have received your comment, and posted it on the web site.<br/>
+      You will be sent back to the article...
+      {% endblocktrans %}
+    </p>
+
+    <p><a href="{{ comment.content_object.get_absolute_url }}#c{{ comment.id }}">{% trans "Back to the article" %}</a></p>
+{% endblock %}