.. _template tags:

======================
Birdland Template Tags
======================

Birdland provides several convenience `template tags`_ for pulling Birdland
blog data into template context outside of Birdland views. To use any of these
tags the following must be present in the template prior to the site of their
use::

    {% load birdland_tags %}

Here is the full list of these tags and examples of their use.

Default Template Tags
=====================

The following template tags are provided by default.

entry_authors_list
------------------

Retrieves a list of ``django.contrib.auth.models.User`` objects associated
with all published ``Entry`` objects and stores the list in a context
variable.

Usage::

    {% entry_authors_list as [varname] %}

Example::

    {% entry_authors_list as published_authors %}
    {% for author in published_authors %}
        {{ author.username }}
    {% endfor %}


latest_entries_list
-------------------

Retrieves a list of the latest published ``Entry`` objects and stores this
list in a context variable.

Usage::

    {% latest_entries_list as [varname] %}

Extended usage::

    {% latest_entries_list as [varname] limit [num] %}

If provided, the ``limit [num]`` option will limit the number of returned
entries to a value less than ``[num]``.

Examples::

    {% latest_entries_list as latest %}
    {% for post in latest %}
        {{ post.title }}
    {% endfor %}

    {% latest_entries_list as latest limit 10 %}


latest_entries_for_author_list
------------------------------

Retrieves a list of the latest published ``Entry`` objects for a
``django.contrib.auth.models.User`` instance contained in the given
context variable and stores this list in another context variable.

Usage::

    {% latest_entries_for_author_list [user-varname] as [varname] %}

Extended usage::

    {% latest_entries_for_author_list [user-varname] as [varname] limit [num] %}

If provided, the ``limit [num]`` argument will limit the length of the
returned list to less than or equal to ``[num]``.

Examples::

    {% latest_entries_for_author_list entry.author as author_latest %}
    {% latest_entries_for_author_list entry.author as author_latest limit 5 %}


entry_years_list
----------------

Retrieves a list of ``datetime.datetime`` objects representing the years
for which there are published ``Entry`` objects and stores this list in
a context variable.

Usage::

    {% entry_years_list as [varname] %}

Example::

    {% entry_years_list as entry_years %}


entry_months_list
-----------------

Retrieves a list of ``datetime.datetime`` objects representing the months
for which there are published ``Entry`` objects for a given year and
stores this list in a context variable.

The given year may be either the year in string format or the name of
a context variable containing a string, integer, or ``datetime.datetime``
object.

Usage::

    {% entry_months_list [year-varname] as [varname] %}

Example::

    {% entry_months_list entry.publish.year as other_months %}

This tag may be used in conjunction with ``entry_years_list`` to build
a date-based archive menu, as is shown in the extended example.

Extended example::

    {% entry_years_list as entry_years %}
    <ul>
        {% for entry_year in entry_years %}
        <li>
            <h4>{{ entry_year.year }}</h4>
            <ul>
                {% entry_months_list entry_year as entry_months %}
                {% for entry_month in entry_months %}
                    <li>{{ entry_month|date:"M" }}</li>
                {% endfor %}
            </ul>
        </li>
        {% endfor %}
    </ul>


Tagging Enabled Tags
====================

The following template tags are only available if tagging integration
is enabled.

tags_for_entries
----------------

Retrieves a list of ``Tag`` objects associated with any Entry object
and stores them in a context variable.

Usage::

   {% tags_for_entries as [varname] %}

Extended usage::

   {% tags_for_entries as [varname] with counts %}

If specified - by providing extra ``with counts`` arguments - adds
a ``count`` attribute to each tag containing the number of Entry
instances which have been tagged with it.

Examples::

   {% tags_for_entries as blog_tags %}
   {% tags_for_entries as blog_tags with counts %}

This is a slight reworking of django-tagging's ``tags_for_model`` tag.


tag_cloud_for_entries
---------------------

Retrieves a list of ``Tag`` objects for entries, with tag
cloud attributes set, and stores them in a context variable.

Usage::

   {% tag_cloud_for_entries as [varname] %}

Extended usage::

   {% tag_cloud_for_entries as [varname] with [options] %}

Extra options can be provided after an optional ``with`` argument,
with each option being specified in ``[name]=[value]`` format. Valid
extra options are:

   ``steps``
      Integer. Defines the range of font sizes.

   ``min_count``
      Integer. Defines the minimum number of times a tag must have
      been used to appear in the cloud.

   ``distribution``
      One of ``linear`` or ``log``. Defines the font-size
      distribution algorithm to use when generating the tag cloud.

Examples::

   {% tag_cloud_for_entries as blog_tags %}
   {% tag_cloud_for_entries as blog_tags with steps=9 min_count=3 distribution=log %}


tags_for_entry
--------------

Retrieves a list of ``Tag`` objects associated with an entry and
stores them in a context variable.

Usage::

   {% tags_for_entry [entry] as [varname] %}

Example::

    {% tags_for_entry foo_object as tag_list %}

This is a light wrapper around django-tagging's ``tags_for_object`` tag.


tagged_entries
--------------

Retrieves a list of entries which are tagged with a given ``Tag``
and stores them in a context variable.

Usage::

   {% tagged_entries [tag] as [varname] %}

The tag must be an instance of a ``Tag``, not the name of a tag.

Example::

    {% tagged_entries comedy_tag as comedies %}

This is a light wrapper around django-tagging's ``tagged_objects`` tag.


related_for_entry
-----------------

Retrieves a list of ``Entry`` objects which have one or more tags in
common with the given ``Entry`` object.

Usage::

    {% related_for_entry [entry] as [varname] %}

Extended Usage::

    {% related_for_entry [entry] as [varname] limit [num] %}

If specified - an extra ``limit`` option will limit the number of returned
``Entry`` objects to a quantity less than or equal to the provided ``num``.

Examples::

    {% related_for_entry [entry] as related_posts %}
    {% related_for_entry [entry] as related_posts limit 5 %}

