Welcome to AutoBreadcrumbs’s documentation!¶

Install¶

pip install autobreadcrumbs

1. In your settings file add autobreadcrumbs to your installed apps:

   INSTALLED_APPS = (
       ...
       'autobreadcrumbs',
       ...
   )
   

2. Import default settings:

   from autobreadcrumbs.settings import *
   

3. Register its context processor:

   TEMPLATE_CONTEXT_PROCESSORS = (
       ...
       'autobreadcrumbs.context_processors.AutoBreadcrumbsContext',
       ...
   )
   

   (Order with other context processors don’t matter).

4. Finally add these two lines in your main urls.py:

   import autobreadcrumbs
   autobreadcrumbs.autodiscover()
   

   This is optional but if you don’t do this, all crumbs.py file will be ignored and only titles defined in settings.AUTOBREADCRUMBS_TITLES will be used.

Overview¶

Autobreadcrumbs build breadcrumbs for a view using its url to find other views the url goes through.

Crumb principle is to link a crumb title to an url name. You can’t add a crumb that is not related to an url name.

There are three way to define crumbs:

• In the initial crumb dictionnary settings.AUTOBREADCRUMBS_TITLES;
• At project level in a crumb module that will be loaded from defined Python path in settings.AUTOBREADCRUMBS_ROOT_CRUMB;
• Per application with a crumb module in your application enabled from settings.INSTALLED_APPS;

The first way is a simple dictionnary to populate. The other ways use Python modules that will directly manage crumbs using the registry interface.

When crumbs are defined, they need to be discovered so they can be loaded to populate registry.

Finally the template context processor is in charge to resolve breadcrumbs for current ressource (a view instance) and push resolved datas in template context.

from django.conf.urls import include, url
from django.views.generic.base import TemplateView

urlpatterns = [
    url(r'^$', TemplateView.as_view(
        template_name="page.html"
    ), name='home'),

    url(r'^foo/$', TemplateView.as_view(
        template_name="page.html"
    ), name='foo'),

    url(r'^foo/bar/$', TemplateView.as_view(
        template_name="page.html"
    ), name='bar'),
]

AUTOBREADCRUMBS_TITLES = {
    'home': 'Home',
}
# Assume your django project is a 'project/' directory
AUTOBREADCRUMBS_ROOT_CRUMB = 'project.crumbs'

from autobreadcrumbs.registry import breadcrumbs_registry
from django.utils.translation import ugettext_lazy

breadcrumbs_registry.update({
    'foo': 'Foo',
    'bar': ugettext_lazy("Bar"),
})

Home > Foo > Bar

Settings¶

autobreadcrumbs.settings.AUTOBREADCRUMBS_HTML_LINK = u'<a href="{link}">{title}</a>'¶

Template string for crumb item in tag {% autobreadcrumbs_links %}

autobreadcrumbs.settings.AUTOBREADCRUMBS_HTML_SEPARATOR = u' &gt; '¶

Template string for separator item in tag {% autobreadcrumbs_links %}

autobreadcrumbs.settings.AUTOBREADCRUMBS_ROOT_CRUMB = None¶

Optional project level crumbs file, this have to be a correct Python path to a crumb module.

autobreadcrumbs.settings.AUTOBREADCRUMBS_TITLES = {}¶

Initial project crumbs where you can add initial crumbs for your project views.

Template tags¶

Every template tag render crumb title using template syntax with given context (from your view), so you can use something like {{ myvar }} in a title for a view which have the myvar variable available in its context. This means template blocks and filters can be used also.

autobreadcrumbs.templatetags.autobreadcrumb.currentwalkthroughto(parser, token)[source]¶

Template tag to output content if current ressource walk through given url name.

Example

Template tag take one requirement argument name that is an url name to search for in breadcrumbs, if the current ressource crumb walk through it, content inside tag will be rendered:

{% load autobreadcrumb %}
{% currentwalkthroughto 'bar' %}Hello{% endcurrentwalkthroughto %}

autobreadcrumbs.templatetags.autobreadcrumb.current_title_from_breadcrumbs(context)[source]¶

Template tag to output breadcrumb title from current ressource crumb.

Example

{% load autobreadcrumb %}
{% current_title_from_breadcrumbs %}

autobreadcrumbs.templatetags.autobreadcrumb.autobreadcrumbs_tag(context)[source]¶

Template tag to output HTML for full breadcrumbs using template autobreadcrumbs_tag.html.

Example

{% load autobreadcrumb %}
{% autobreadcrumbs_tag %}

autobreadcrumbs.templatetags.autobreadcrumb.autobreadcrumbs_links(context)[source]¶

Template tag which use AUTOBREADCRUMBS_HTML_LINK and AUTOBREADCRUMBS_HTML_SEPARATOR settings to build a HTML list of breadcrumbs.

Returned HTML is marked as safe (not to escape) for templates.

Example

{% load autobreadcrumb %}
{% autobreadcrumbs_links %}

Site registry for breadcrumb definitions¶

class autobreadcrumbs.registry.BreadcrumbSite(*args, **kwargs)[source]¶

Breadcrumbs site registry

Keyword Arguments:
	initial (dict) – Optional initial dictionnary of crumbs urlname->value. Default to an empty dict.

get_names()[source]¶

Return registred crumb url names.

Returns:	List of registred crumb url names, sorted with default sorted() behavior.
Return type:	list

get_registry()[source]¶

Return current registry

Returns:	Currrent registry.
Return type:	dict

get_title(name)[source]¶

Get title for given url name.

Parameters:	name (string) – Url name.
Returns:	Crumb title.
Return type:	string or tuple

has_title(name)[source]¶

Find if given name is registred as a crumb.

Returns:	True if name exists in current registry, else False.
Return type:	bool

register(name, value)[source]¶

Register a crumb for given url name.

Parameters:	name (string) – Url name. value (string or tuple) – Crumb title to define.
Raises:	AlreadyRegistered if the url name is allready registered in crumbs.

reset()[source]¶

Reset registry to an empty Dict.

unregister(name)[source]¶

Unregister a crumb.

Parameters:	name (string) – Url name.
Raises:	NotRegistered if given url name is not registred yet.

update(crumbs)[source]¶

Update many crumbs

This works like the Dict.update({..}) method.

Parameters:	crumbs (dict) – A dict of crumbs (urlname->value).

autobreadcrumbs.registry.breadcrumbs_registry = <autobreadcrumbs.registry.BreadcrumbSite object>¶

Default breadcrumbs site registry for a Django instance.

Crumb definitions discovering¶

Crumb definitions are registred through files that are loaded as Python modules, where some code can register needed crumbs.

autobreadcrumbs.discover.autodiscover(filename='crumbs')[source]¶

Automatic discovering for available crumbs definitions

Before looking at crumbs files, registry start from settings.AUTOBREADCRUMBS_TITLES items if setted, else an empty Dict.

Then it try to load possible root crumb file defined in settings.AUTOBREADCRUMBS_ROOT_CRUMB (as a Python path). And finally load each crumbs file finded in settings.INSTALLED_APPS.

Keyword Arguments:
	filename (string) – Module filename to search for. Default to crumbs, so it will search for a crumbs.py file at root of every enabled module from settings.INSTALLED_APPS.
Returns:	List of successfully loaded Python paths.
Return type:	list

autobreadcrumbs.discover.discover(module_path, filename=None)[source]¶

Try to discover and load a crumbs.py file from given Python path.

Parameters:	module_path (string) – Python path to scan for filename module.
Keyword Arguments:
	filename (string) – Optional module filename to search for, usually crumbs.py, default to None.
Raises:	Exception – Raise any occuring exception from loaded Python path.
Returns:	Python path (module.filename) for discovered crumbs module. If filename does not exists in module, return None.
Return type:	string or None

Breadcrumb resolving¶

class autobreadcrumbs.resolver.BreadcrumbRessource(path, name, title, view_args, view_kwargs)[source]¶

Simple crumb ressource model to contain all datas about a ressource.

class autobreadcrumbs.resolver.PathBreadcrumbResolver(root_urlconf)[source]¶

Resolve given path as breadcrumbs

Parameters:	root_urlconf (string) – Python path to an url conf file, usually settings.ROOT_URLCONF. It will be used as the url map to resolve every given path.

cut(path)[source]¶

Cut given path into segments

Parameters:	path (string) – An url path like /foo/bar/.
Returns:	List of path segments, each segment is a part of the url path starting from / and ending on the full path. Such as for /foo/bar/ segments will be: - / - /foo - /foo/bar
Return type:	list

format_title(value)[source]¶

Manage title format

Parameters:	name (string) – Url name. value (string) – Crumb value.
Keyword Arguments:
	request (django.http.request.HttpRequest) – Optional Django request object used with custom crumb function. If not given, crumb functions is ignored (so the crumb ressource still be available).
Returns:	Crumb title.
Return type:	string

get_current(elements)[source]¶

Return current Breadcrumb from elements.

This is pretty simple as the current element is allways the last element (if element list is not empty).

Parameters:	elements (list) – List of breadcrumb elements.
Returns:	The last element from given elements if any, else None.
Return type:	BreadcrumbRessource or None

resolve(path, request=None)[source]¶

Return resolved breadcrumbs datas from given path.

Cut the path in segments and check each of them to find breadcrumb details if any.

Crumb value can be a simple string, a Django lazy unicode or a tuple (title, custom_function).

Crumb custom_function take url name and request object as arguments and will return False to ignore crumb (won’t be in breadcrumbs) or True to keep crumb element.

Parameters:	path (string) – An url path like /foo/bar/.
Keyword Arguments:
	request (django.http.request.HttpRequest) – Optional Django request object used with custom crumb function. If not given, crumb functions will be ignored (so the crumb ressources still be available).
Returns:	Datas from resolved crumbs: autobreadcrumbs_elements: Resolved bread crumbs for each segment; autobreadcrumbs_current: Breadcrumb for current (the last one) path.
Return type:	Dict

Template context processor¶

autobreadcrumbs.context_processors.AutoBreadcrumbsContext(request)[source]¶

Context processor to resolve breadcrumbs from current ressource.

Use request.path to know the current ressource url path and settings.ROOT_URLCONF to resolve it.

Development¶

mkdir autobreadcrumbs-dev
cd autobreadcrumbs-dev
virtualenv .
source bin/activate
pip install -r https://raw.githubusercontent.com/sveetch/autobreadcrumbs/master/requirements/dev.txt

make tests

sudo pip install tox

tox

Changelog¶