Template Tag Reference
======================

django-crumbs provides two template tags: ``add_crumb`` and ``render_breadcrumbs``.
These template tags can be accessed by loading ``breadcrumb_tags`` in your template.

.. code-block:: django

    {% load breadcrumb_tags %}


``add_crumb``
-------------

The ``add_crumb`` tag may be used to add a breadcrumb either with or without an html
anchor link.  For a crumb without a link, simply provide the breadcrumb text.

.. code-block:: django

    {% add_crumb 'Home' %}

For a crumb with a link, provide the crumb text and either a url value or (better) the
name of a url pattern to reverse in order to geneate the url.

.. code-block:: django

    {% add_crumb 'Home' '/home' %}
    {% add_crumb 'Home' 'project-home' %}

The django-crumbs code assumes ``url`` arguments that contain slashes are already reversed
and thus does not call reverse on these. However, it is generally better practice to avoid
hard-coding url values in in templates, so this form should not be used unless absolutely
necessary (if for some reason the target url value cannot be generated by a call to
``reverse``).

The crumb and url arguments to the ``add_crumb`` tag may also be specified using keyword
syntax.

.. code-block:: django

    {% add_crumb crumb='Home' url='project-home' %}

When passing a url pattern name to be reversed, additional arguments specified to ``add_crumb``
will be passed to the ``reverse`` call as ``args``.

.. code-block:: django

    {% add_crumb 'Details' 'detail-view' 44 %}

The above call will result in a call to the ``django.core.urlresolvers`` ``reverse`` function:

.. code-block:: python

    reverse('detail-view', args=(44,))

The value returned from ``reverse`` will be the ``href`` value for the anchor link rendered
with the breadcrumb.

*Note:* Additional arguments for the reverse call cannot be passed using keyword syntax.


``render_breadcrumbs``
----------------------

The ``render_breadcrumbs`` tag renders the breadcrubs accumulated by previous calls to
``add_crumb``, if there have been at least two calls to ``add_crumb``. ``render_breadcrumbs``
takse no arguments.

The template used for rendering is ``breadcrumbs/crubms.html``. django-crumbs provides a
default template for this rendering in ``crumbs/templates/breadcrumbs/crumbs.html``:

.. literalinclude:: ../crumbs/templates/breadcrumbs/crumbs.html
   :language: django

If you would like to customize the rendering, you may override this template in your own
project. The template is passed a sequence of ``(crumb, href)`` tuples in the ``crumbs``
context variable (crumbs without links will have empty ``href`` values in this sequence).