django-url-breadcrumbs 0.3.3

Installation

1. Install the package from PyPi. For example via pip:

   pip install django-url-breadcrumbs

2. Add urlbreadcrumbs to INSTALLED_APPS:

   INSTALLED_APPS = (
       ...
       'urlbreadcrumbs',
       ...
   )

3. Make sure you have a request context processor django.core.context_processors.request in your TEMPLATE_CONTEXT_PROCESSORS.

Usage

Let’s assume you have your urls in a form:

in ROOT_URLCONF:

from django.conf.urls import patterns, include, url
from myproject.views import some_view

urlpatterns = patterns('',
    url(r'^$', some_view, {'template' : 'index.html'}, name='index'),
    url(r'^test1/', include('test1.urls')),
)

urls.py in application called test1:

from django.conf.urls import patterns, include, url
from test1.views import some_view

urlpatterns = patterns('',
    url(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home'),
)

In order to define your breadcrumbs you can make a mapping in settings.py like this:

URLBREADCRUMBS_NAME_MAPPING = {
    'index'  : 'Home page',
    't1home' : 'Index page of Test1',
}

Then somwhere in your base template (lets call it base.html) you can write this:

{% load urlbreadcrumbs_tags %}
{% render_breadcrumbs %}

or you can specify your own template:

{% render_breadcrumbs "test1/mybreadcrumbs_template.html" %}

Also you can just include your breadcrumbs template:

{% include "test1/mybreadcrumbs_template.html" %}

But to use it like this make sure you’ve added a context procesor urlbreadcrumbs.context_processors.build_breadcrumbs in your TEMPLATE_CONTEXT_PROCESSORS setting.

In your template you have one additional context variable called breadcrumbs which is a list of two-tuples containing name and url of a breadcrumb. The default template used by django-url-breadcrumbs (urlbreadcrumbs/default.html) looks like this:

{% for n,u in breadcrumbs %}
    {% if not forloop.last %}
        <a href="{{ u }}">{{ n }}</a> &raquo;
    {% else %}
        {{ n }}
    {% endif %}
{% endfor %}

So now, assuming template t1.html is extending base.html, when viewing /test1/example/ you should see something like this Home page » Index page of Test1.

Another way of specyfing a name for a breadcrumb is to use a custom url function in your urls.py. Instead of defining a mapping in URLBREADCRUMBS_NAME_MAPPING setting you can do this in urls.py of your ROOT_URLCONF and test1 application:

from django.conf.urls import patterns, include, url
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    ...
    burl(r'^test1/', include(test1_urls)),
    ...
)

and

from django.conf.urls import patterns, include, url
from test1.views import some_view
from urlbreadcrumbs import url as burl

urlpatterns = patterns('',
    burl(r'^example/$', some_view, {'template' : 't1.html'}, name='t1home', verbose_name='Index page of Test1'),
)

This should work as in previous example.

Development

Ideas and/or bug reports are welcome. Consider reporting an issue on https://bitbucket.org/slafs/django-url-breadcrumbs/issues?status=new&status=open

Pull requests are also welcome ;).

To start working on this app get the source from Bitbucket:

hg clone https://bitbucket.org/slafs/django-url-breadcrumbs

and in a newly created virtualenv do this:

pip install -r dev_requirements.txt
python setup.py test

python setup.py test

tox