/docs/tags.txt

 1====================================
 2Template tags for moderated comments
 3====================================
 4
 5
 6The built-in template tags included with ``django.contrib.comments``
 7for retrieving lists and counts of comments for specific objects are
 8useful, but when mixed with an application which uses comment
 9moderation they become problematic, because these tags look at _all_
10comments, rather than just those comments which are marked with
11``is_public=True``. This can lead to excessive template logic to
12exclude moderated (non-public) comments from public display, and no
13workaround is possible within a template for seemingly-erroneous
14comment counts.
15
16To solve these problems, ``comment_utils`` includes a set of tags
17which closely mimic the built-in comment list and comment count tags,
18but which do take the ``is_public`` field into account. At the moment,
19they do not take into account the ``is_removed`` field on ``Comment``
20or the ``approved`` field on ``FreeComment``, though a future version
21of ``comment_utils`` may add support for this.
22
23Before using any of these tags in your templates, remember to load
24them with ``{% load comment_utils %}``.
25
26
27``get_public_comment_count``
28----------------------------
29
30Nearly identical to Django's built-in ``get_comment_count`` tag;
31returns the number of public ``Comment`` objects attached to a given
32object.
33
34Syntax::
35    
36    {% get_public_comment_count for [app_name].[model_name] [object_id] as [varname] %}
37
38Example::
39
40    {% get_public_comment_count for blog.entry entry.id as comment_count %}
41
42
43``get_public_free_comment_count``
44----------------------------------
45
46Nearly identical to Django's built-in ``get_free_comment_count`` tag;
47returns the number of public ``FreeComment`` objects attached to a given
48object.
49
50Syntax::
51    
52    {% get_public_free_comment_count for [app_name].[model_name] [object_id] as [varname] %}
53
54Example::
55
56    {% get_public_free_comment_count for blog.entry entry.id as comment_count %}
57
58
59``get_public_comment_list``
60---------------------------
61
62Nearly identical to Django's built-in ``get_comment_list`` tag;
63returns a list of public ``Comment`` objects attached to a given
64object.
65
66Syntax::
67
68    {% get_public_comment_list for [app_name].[model_name] [object_id] as [varname] %}
69
70Example::
71
72    {% get_public_comment_list for blog.entry entry.id as comment_list %}
73
74
75``get_public_free_comment_list``
76--------------------------------
77
78Nearly identical to Django's built-in ``get_free_comment_list`` tag;
79returns a list of public ``FreeComment`` objects attached to a given
80object.
81
82Syntax::
83
84    {% get_public_free_comment_list for [app_name].[model_name] [object_id] as [varname] %}
85
86Example::
87
88    {% get_public_free_comment_list for blog.entry entry.id as comment_list %}