julioriffel/django-view-breadcrumbs

Breadcrumb mixins for django views. Create breadcrumbs in seconds.

django-view-breadcrumbs

Provides a set of breadcrumb mixin classes that can be added to any django view.

Requires adding {% render_breadcrumbs %} to just the base template.

In the base.html template simply add the render_breadcrumbs tag and any template that inherits the base should have breadcrumbs included. i.e

base.html

{% load view_breadcrumbs %}

{% block breadcrumbs %}
    {% render_breadcrumbs %} {# Optionally provide a template e.g {% render_breadcrumbs "view_breadcrumbs/bootstrap5.html" %} #}
{% endblock %}

And your create.html.

{% extends "base.html" %}

Breadcrumb mixin classes provided.

• BaseBreadcrumbMixin - Base view requires a crumbs class property.
• CreateBreadcrumbMixin - For create views Home / Posts / Add Post
• DetailBreadcrumbMixin - For detail views Home / Posts / Post 1
• ListBreadcrumbMixin - For list views Home / Posts
• UpdateBreadcrumbMixin - For Update views Home / Posts / Post 1 / Update Post 1
• DeleteBreadcrumbMixin - For Delete views this has a link to the list view to be used as the success URL.

Installation

$ pip install django-view-breadcrumbs

Add view_breadcrumbs to your INSTALLED_APPS

INSTALLED_APPS = [
    ...,
    "view_breadcrumbs",
    ...,
]

Settings

NOTE ⚠️

• Make sure that "django.template.context_processors.request" is added to your TEMPLATE OPTIONS setting.

TEMPLATES  = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request", # <- This context processor is required
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

Modify the defaults using the following:

Name	Default	Description	Options
BREADCRUMBS_TEMPLATE	"view_breadcrumbs/bootstrap4.html"	Template used to render breadcrumbs.	Predefined Templates
BREADCRUMBS_HOME_LABEL	Home	Default label for the root path

Customization

BREADCRUMBS_TEMPLATE

Site wide:

BREADCRUMBS_TEMPLATE = "my_app/breadcrumbs.html"

For just the base template:

Update the base.html

{% render_breadcrumbs "my_app/breadcrumbs.html" %}

BREADCRUMBS_HOME_LABEL

Site wide:

BREADCRUMBS_HOME_LABEL = "My new home"

For just a single view:

See: Overriding the Home label for a specific view

Renders

Translation support

Example

Usage

django-view-breadcrumbs includes generic mixins that can be added to a class based view.

Using the generic breadcrumb mixin each breadcrumb will be added to the view dynamically and can be overridden by providing a crumbs property.

View Configuration

NOTE: ⚠️

• Model based views should use a pattern view_name=model_verbose_name_{action}

Actions	View Class	View name	Sample Breadcrumb
list	ListView	{model.verbose_name}_list	Home / Posts
create	CreateView	{model.verbose_name}_create	Home / Posts / Add Post
detail	DetailView	{model.verbose_name}_detail	Home / Posts / Test - Post
change	UpdateView	{model.verbose_name}_update	Home / Posts / Test - Post / Update Test - Post
delete	DeleteView	{model.verbose_name}_delete	N/A

Optionally this can use the following class properties instead of hardcoding the view names.

...
    path("tests/", TestListsView.as_view(), name=TestListsView.list_view_name),
    path(
        "tests/<slug:slug>/",
        TestDetailView.as_view(),
        name=TestDetailView.detail_view_name,
    ),
    path(
        "tests/<slug:slug>/update/",
        TestUpdateView.as_view(),
        name=TestUpdateView.update_view_name,
    ),
    path(
        "tests/<slug:slug>/delete/",
        TestDeleteView.as_view(),
        name=TestDeleteView.delete_view_name,
    ),
...

For views classes like: TemplateView | AboutView | View

See: Custom View

For usage with django tables 2

See: demo table view

For more examples see: demo app

Sample crumbs: Home / Posts / Test - Post

In your urls.py

  urlpatterns = [
      ...
      path("posts/<slug:slug>/", views.PostDetail.as_view(), name="post_detail"),
      ...
      # OR
      ...
      path("posts/<slug:slug>/", views.PostDetail.as_view(), name=views.PostDetail.detail_view_name),
      ...
  ]

views.py

from django.views.generic import DetailView
from view_breadcrumbs import DetailBreadcrumbMixin


class PostDetail(DetailBreadcrumbMixin, DetailView):
    model = Post
    template_name = "app/post/detail.html"
    breadcrumb_use_pk = False

Sample crumbs: Posts

In your urls.py

  urlpatterns = [
      ...
      path("posts/", views.PostList.as_view(), name="post_list"),
      ...
      # OR
      ...
      path("posts/", views.PostList.as_view(), name=views.PostList.list_view_name),
      ...
  ]

All crumbs use the home root path / as the base this can be excluded by specifying add_home = False

from django.views.generic import ListView
from view_breadcrumbs import ListBreadcrumbMixin


class PostList(ListBreadcrumbMixin, ListView):
    model = Post
    template_name = "app/post/list.html"
    add_home = False

Custom crumbs: Home / My Test Breadcrumb

URL configuration.

    urlpatterns = [
       path("my-custom-view/", views.CustomView.as_view(), name="custom_view"),
    ]

views.py

from django.urls import reverse
from django.views.generic import View
from view_breadcrumbs import BaseBreadcrumbMixin
from demo.models import TestModel


class CustomView(BaseBreadcrumbMixin, View):
    model = TestModel
    template_name = "app/test/custom.html"
    crumbs = [("My Test Breadcrumb", reverse("custom_view"))]  # OR reverse_lazy

OR

from django.urls import reverse
from django.views.generic import View
from view_breadcrumbs import BaseBreadcrumbMixin
from demo.models import TestModel
from django.utils.functional import cached_property


class CustomView(BaseBreadcrumbMixin, View):
    template_name = "app/test/custom.html"

    @cached_property
    def crumbs(self):
        return [("My Test Breadcrumb", reverse("custom_view"))]

Overriding the Home label for a specific view

from django.utils.translation import gettext_lazy as _
from view_breadcrumbs import DetailBreadcrumbMixin
from django.views.generic import DetailView
from demo.models import TestModel


class TestDetailView(DetailBreadcrumbMixin, DetailView):
     model = TestModel
     home_label = _("My custom home")
     template_name = "demo/test-detail.html"

Refer to the demo app for more examples.

Running locally

$ make install-dev
$ make migrate
$ make run

Spins up a django server running the demo app.

Visit http://127.0.0.1:8090

Credits

• django-bootstrap-breadcrumbs

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Derek 📖

This project follows the all-contributors specification. Contributions of any kind welcome!