django-crumbs provides two template tags: add_crumb
and render_breadcrumbs
.
These template tags can be accessed by loading breadcrumb_tags
in your template.
{% 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.
{% 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.
{% 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.
{% 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
.
{% add_crumb 'Details' 'detail-view' 44 %}
The above call will result in a call to the django.core.urlresolvers
reverse
function:
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
:
{% for crumb, href in crumbs %}
{% if not forloop.last %}
{% if href %}
<a href='{{ href }}' title='Go back to {{ crumb }}'>{{ crumb }}</a> »
{% else %}
{{ crumb }} »
{% endif %}
{% else %}
<span class='leaf'>{{ crumb }}</span>
{% endif %}
{% endfor %}
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).