django-dynamic-breadcrumbs’s documentation¶

django-dynamic-breadcrumbs is a Django app to generate HTML breadcrumbs dynamically from URL paths.

How does it work¶

A request is handled by Django at a specific URL:

https://example.com/reference/instrument/guitar/
A context processor analyze the URL, and extracts the path:

/reference/instrument/guitar/
For each part separated by / tries to resolve it and get the specific View that handles that URL.
Adds to the request context a list of names and urls

home       -> https://example.com
reference  -> https://example.com/reference
instrument -> https://example.com/reference/instrument
guitar

The template shows the above list with links for each level

Home > Reference > Instrument > Guitar

Indices and tables¶

Installation¶

Django-dynamic-breadcrumbs can be installed from PyPI with tools like pip:

$ pip install django-dynamic-breadcrumbs

Then add 'dynamic_breadcrumbs' to your INSTALLED_APPS.

INSTALLED_APPS = [
    ...
    'dynamic_breadcrumbs',
]

Requirements¶

Django-dynamic-breadcrumbs is tested against these supported versions of Python and Django

Python: 3.8
Django: 3.2

Getting Started¶

Add to settings¶

Add dynamic_breadcrumbs.context_processors.breadcrumbs to context_processors:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [os.path.join(BASE_DIR, "templates")],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                                #...
                "dynamic_breadcrumbs.context_processors.breadcrumbs",
            ],
        },
    },
]

Add template¶

Include the dynamic_breadcrumbs/breadcrumbs.html in your base template.

{% if breadcrumbs %}
<div class="container">
    {% include "dynamic_breadcrumbs/breadcrumbs.html" with breadcrumbs=breadcrumbs%}
</div>
{% endif %}

Settings Reference¶

List of all available settings of django-dynamic-breadcrumbs and their default values.

All settings are prefixed with DYNAMIC_BREADCRUMBS_.

DYNAMIC_BREADCRUMBS_HOME_LABEL¶

Default: 'Home'

Set the default base Url to be shown as the first item of the breadcrumb list.

DYNAMIC_BREADCRUMBS_SHOW_AT_BASE_PATH¶

Default: False

Wheter to show or hide breadcrumbs at site’s root.

DYNAMIC_BREADCRUMBS_PATH_ONLY_ALPHANUMERIC¶

Default: True

Only allows alphanumeric characters in breadcrumb item names. If someone contains non-alphanumeric values it will show an empty string.

DYNAMIC_BREADCRUMBS_PATH_MAX_DEPTH¶

Default: 5

The maximum number of breadcrumb items to show

DYNAMIC_BREADCRUMBS_PATH_MAX_COMPONENT_LENGTH¶

Default: 50

Each path component’s maximum length.

Running the Test Suite¶

To run the django-dynamic-breadcrumbs tests checkout the source code and create a virtualenv where you can install the test dependencies.

Note

The following assumes you have virtualenv and git installed.

Clone the repository¶

Get the source code using the following command:

$ git clone https://github.com/marcanuy/django-dynamic-breadcrumbs.git

Switch to the django-dynamic-breadcrumbs directory:

$ cd django-dynamic-breadcrumbs

Set up the virtualenv¶

Create a new virtualenv to run the test suite in:

$ python3 -m venv ~/.virtualenvs/django-dynamic-breadcrumbs

Then activate the virtualenv and install the test requirements:

$ source ~/.virtualenvs/django-dynamic-breadcrumbs/bin/activate
$ pip install -r requirements/test.txt

Execute the test runner¶

Run the tests with the runner script:

$ make tests-run

Test all supported versions¶

To run the tests against all supported versions of Python and Django use tox, then:

$ tox

Formatting¶

Python code is formatted with black

$ black .