.. _ref-templatetags:

.. index::
   pair: Filters; Templatetags

=========================
Filters and Template Tags
=========================

Django-comments-xtd comes with 4 tags and two filters:

 * Tag :ttag:`get_xtdcomment_tree`
 * Tag :ttag:`get_xtdcomment_count`
 * Tag :ttag:`get_last_xtdcomments`
 * Filter :ttag:`xtd_comment_gravatar`
 * Tag :ttag:`render_last_xtdcomments`
 * Filter :ttag:`render_markup_comment`

To use any of them in your templates you first need to load them::

    {% load comments_xtd %}


.. index::
   single: get_xtdcomment_tree
   pair: tag; get_xtdcomment_tree

.. templatetag:: get_xtdcomment_tree

Get Xtdcomment Tree
===================

Tag syntax:

   .. code-block:: html+django

       {% get_xtdcomment_tree for [object] as [varname] %}


Returns a dictionary to the template context under the name given in ``[varname]`` with the comments posted to the given ``[object]``. The dictionary has the form:

   .. code-block:: python

       {
           'xtdcomment': xtdcomment_object,
           'children': [ list_of_child_xtdcomment_dicts ]
       }

The comments will be ordered by the ``thread_id`` and ``order`` within the thread, as stated by the setting :setting:`COMMENTS_XTD_LIST_ORDER`. 
       
Example usage
-------------

Get an ordered dictionary with the comments posted to a given blog story and store the dictionary in a template context variabled called ``comment_tree``:

   .. code-block:: html+django

       {% get_xtdcomment_tree for story as comments_tree %}

    
.. index::
   single: get_xtdcomment_count
   pair: tag; get_xtdcomment_count

.. templatetag:: get_xtdcomment_count

Get Xtdcomment Count
====================

Tag syntax::

    {% get_xtdcomment_count as [varname] for [app].[model] [[app].[model] ...] %}

Gets the comment count for the given pairs ``<app>.<model>`` and populates the template context with a variable containing that value, whose name is defined by the ``as`` clause.


Example usage
-------------

Get the count of comments the model ``Story`` of the app ``blog`` have received, and store it in the context variable ``comment_count``::

    {% get_xtdcomment_count as comment_count for blog.story %}

Get the count of comments two models, ``Story`` and ``Quote``, have received and store it in the context variable ``comment_count``::

    {% get_xtdcomment_count as comment_count for blog.story blog.quote %}


.. index::
   single: get_last_xtdcomments
   pair: tag; get_last_xtdcomments

Get Last Xtdcomments
====================

Tag syntax::

    {% get_last_xtdcomments [N] as [varname] for [app].[model] [[app].[model] ...] %}

Gets the list of the last N comments for the given pairs ``<app>.<model>`` and stores it in the template context whose name is defined by the ``as`` clause.

Example usage
-------------

Get the list of the last 10 comments two models, ``Story`` and ``Quote``, have received and store them in the context variable ``last_10_comment``. You can then loop over the list with a ``for`` tag::

    {% get_last_xtdcomments 10 as last_10_comments for blog.story blog.quote %}
    {% if last_10_comments %}
      {% for comment in last_10_comments %}
        <p>{{ comment.comment|linebreaks }}</p> ...
      {% endfor %}
    {% else %}
      <p>No comments</p>
    {% endif %}


.. index::
   single: xtd_comment_gravatar

.. templatetag:: xtd_comment_gravatar

Xtd Comment Gravatar
====================

Filter syntax::

  {{ comment.email|xtd_comment_gravatar }}

A simple gravatar filter that inserts the `gravatar <http://www.gravatar.com/>`_ image associated to an email address.

This filter has been named ``xtd_comment_gravatar`` as oposed to simply ``gravatar`` to avoid potential name collisions with other gravatar filters the user might have opted to include in the template.


.. index::
   single: render_last_xtdcomments
   pair: tag; render_last_xtdcomments

Render Last Xtdcomments
=======================

Tag syntax::

    {% render_last_xtdcomments [N] for [app].[model] [[app].[model] ...] %}

Renders the list of the last N comments for the given pairs ``<app>.<model>`` using the following search list for templates:

 * ``django_comments_xtd/<app>/<model>/comment.html``
 * ``django_comments_xtd/<app>/comment.html``
 * ``django_comments_xtd/comment.html``

Example usage
-------------

Render the list of the last 5 comments posted, either to the blog.story model or to the blog.quote model. See it in action in the *Multiple Demo Site*, in the *blog homepage*, template ``blog/homepage.html``::

    {% render_last_xtdcomments 5 for blog.story blog.quote %}


.. index::
   single: render_markup_comment, Markdown; reStructuredText
   pair: filter; render_markup_comment

.. templatetag:: render_markup_comment
   
Render Markup Comment
=====================

Filter syntax:

   .. code-block:: html+django

       {{ comment.comment|render_markup_comment }}


Renders a comment using a markup language specified in the first line of the comment. It uses `django-markup <https://github.com/bartTC/django-markup>`_ to parse the comments with a markup language parser and produce the corresponding output.

Example usage
-------------

A comment posted with a content like:

   .. code-block:: text

       #!markdown
       An [example](http://url.com/ "Title")

Would be rendered as a markdown text, producing the output:

   .. code-block:: html
       
       <p><a href="http://url.com/" title="Title">example</a></p>

Available markup languages are:

 * `Markdown <http://daringfireball.net/projects/markdown/syntax>`_, when starting the comment with ``#!markdown``.
 * `reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, when starting the comment with ``#!restructuredtext``.
 * Linebreaks, when starting the comment with ``#!linebreaks``.
