Skip to main content

Django generic view breadcrumbs

Project description

django-view-breadcrumbs

Build Status PyPI - Django Version PyPI - Python Version Downloads

Codacy Badge Codacy Badge PyPI version Updates All Contributors

Provides a generic set of breadcrumb mixin classes.

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

Screenshot

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 :warning:

  • 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

To modify the root label site wide use

BREADCRUMBS_HOME_LABEL - Sets the root label (default: Home)

Example

BREADCRUMBS_HOME_LABEL = "My new home"

Renders

Screenshot

Using django's translation support

Translated Screenshot

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: :warning:

  • 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 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-test-list-view/", views.TestView.as_view(), name="test_list_view"),
       path("my-test-detail-view/<int:pk>/", views.TestView.as_view(), name="test_detail_view"),
    ]

Can override the view breadcrumb by specifying a list of tuples [(label, view path)].

views.py

from django.urls import reverse
from django.views.generic import ListView
from view_breadcrumbs import ListBreadcrumbMixin
from demo.models import TestModel


class TestView(ListBreadcrumbMixin, ListView):
    model = TestModel
    template_name = "app/test/test-list.html"
    crumbs = [("My Test Breadcrumb", reverse("test_list_view"))]  # OR reverse_lazy

OR

from django.urls import reverse
from django.views.generic import ListView
from view_breadcrumbs import ListBreadcrumbMixin
from demo.models import TestModel
from django.utils.functional import cached_property


class TestView(ListBreadcrumbMixin, ListView):
    model = TestModel
    template_name = "app/test/test-list.html"

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

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Derek

📖

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-view-breadcrumbs, version 2.1.1
Filename, size File type Python version Upload date Hashes
Filename, size django_view_breadcrumbs-2.1.1-py3-none-any.whl (23.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-view-breadcrumbs-2.1.1.tar.gz (66.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page