Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tj-django/django-view-breadcrumbs
Breadcrumb mixins for django views. Create breadcrumbs in seconds.
https://github.com/tj-django/django-view-breadcrumbs
breadcrumb-mixin breadcrumb-mixins breadcrumbs breadcrumbs-template custom-crumbs customview detailview django django-bootstrap-breadcrumbs django-breadcrumbs django-views listview sample-crumbs translation-support urlpatterns
Last synced: about 11 hours ago
JSON representation
Breadcrumb mixins for django views. Create breadcrumbs in seconds.
- Host: GitHub
- URL: https://github.com/tj-django/django-view-breadcrumbs
- Owner: tj-django
- License: bsd-3-clause
- Created: 2018-01-19T01:30:27.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-23T17:33:30.000Z (25 days ago)
- Last Synced: 2024-11-08T14:05:41.652Z (9 days ago)
- Topics: breadcrumb-mixin, breadcrumb-mixins, breadcrumbs, breadcrumbs-template, custom-crumbs, customview, detailview, django, django-bootstrap-breadcrumbs, django-breadcrumbs, django-views, listview, sample-crumbs, translation-support, urlpatterns
- Language: Python
- Homepage: https://tj-django.github.io/django-view-breadcrumbs/#/
- Size: 950 KB
- Stars: 76
- Watchers: 3
- Forks: 8
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# django-view-breadcrumbs
[](https://github.com/tj-django/django-view-breadcrumbs/actions/workflows/test.yml) [](https://www.codacy.com/gh/tj-django/django-view-breadcrumbs/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=tj-django/django-view-breadcrumbs\&utm_campaign=Badge_Grade) [](https://results.pre-commit.ci/latest/github/tj-django/django-view-breadcrumbs/main) [](https://www.codacy.com/gh/tj-django/django-view-breadcrumbs/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=tj-django/django-view-breadcrumbs\&utm_campaign=Badge_Coverage) [](https://badge.fury.io/py/django-view-breadcrumbs)
 
[](https://pepy.tech/project/django-view-breadcrumbs)
[](#contributors-)
## Table of Contents
* [Background](#background)
* [Installation](#installation)
* [Add `view_breadcrumbs` to your INSTALLED\_APPS](#add-view_breadcrumbs-to-your-installed_apps)
* [Breadcrumb mixin classes provided.](#breadcrumb-mixin-classes-provided)
* [Settings](#settings)
* [Customization](#customization)
* [BREADCRUMBS\_TEMPLATE](#breadcrumbs_template)
* [Site wide](#site-wide)
* [Overriding the breadcrumb template for a single view](#overriding-the-breadcrumb-template-for-a-single-view)
* [BREADCRUMBS\_HOME\_LABEL](#breadcrumbs_home_label)
* [Site wide](#site-wide-1)
* [Overriding the Home label for a specific view](#overriding-the-home-label-for-a-specific-view)
* [Translation support](#translation-support)
* [Example](#example)
* [Usage](#usage)
* [View Configuration](#view-configuration)
* [django-tables-2](#django-tables-2)
* [URL Configuration](#url-configuration)
* [Examples](#examples)
* [Sample crumbs: `Posts`](#sample-crumbs-posts)
* [Sample crumbs: `Home / Posts / Test - Post`](#sample-crumbs--home--posts--test---post)
* [Custom crumbs: `Home / My Test Breadcrumb`](#custom-crumbs-home--my-test-breadcrumb)
* [Using multiple apps](#using-multiple-apps)
* [Running locally](#running-locally)
* [Credits](#credits)
* [Contributors ✨](#contributors-)
## Background
This package provides a set of breadcrumb mixin classes that can be added to any django class based view and requires adding just `{% render_breadcrumbs %}` to the base template.
In the `base.html` template add the `render_breadcrumbs` tag and any template that inherits the base should have breadcrumbs included.
**Example:**
my_app
|--templates
|--base.html
|--create.html
`base.html`
```jinja2
{% load view_breadcrumbs %}
{% block breadcrumbs %}
{% render_breadcrumbs %} {# Optionally provide a custom template e.g {% render_breadcrumbs "view_breadcrumbs/bootstrap5.html" %} #}
{% endblock %}
```
And your `create.html`.
```jinja2
{% extends "base.html" %}
```
## Installation
```bash
$ pip install django-view-breadcrumbs
```
### Add `view_breadcrumbs` to your INSTALLED\_APPS
```python
INSTALLED_APPS = [
...,
"view_breadcrumbs",
...,
]
```
## Breadcrumb mixin classes provided.
* `BaseBreadcrumbMixin` - Subclasses 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.
## Settings
> NOTE :warning:
>
> * Make sure that `"django.template.context_processors.request"` is added to your TEMPLATE OPTIONS setting.
```python
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/bootstrap5.html"` | Template used to render breadcrumbs. | [Predefined Templates](https://github.com/tj-django/django-view-breadcrumbs/tree/main/view_breadcrumbs/templates/view_breadcrumbs) |
| `BREADCRUMBS_HOME_LABEL` | `Home` | Default label for the root path | |
### Customization
#### BREADCRUMBS\_TEMPLATE
##### Site wide
```python
BREADCRUMBS_TEMPLATE = "my_app/breadcrumbs.html"
```
##### Overriding the breadcrumb template for a single view
Update the `base.html`
```jinja2
{% render_breadcrumbs "my_app/breadcrumbs.html" %}
```
#### BREADCRUMBS\_HOME\_LABEL
##### Site wide
```python
BREADCRUMBS_HOME_LABEL = "My new home"
```
##### Overriding the Home label for a specific view
```python
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 new home")
template_name = "demo/test-detail.html"
```
*Renders*
## [Translation support](https://docs.djangoproject.com/en/3.1/topics/i18n/translation/)
### 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: :warning:
>
> * Model based views should use a pattern `view_name=model_verbose_name_{action}`
| Actions | View Class | View name | Sample Breadcrumb | Example |
|-----------|-------------|-------------|-------------------|----------|
| `list` | [`ListView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-display/#listview) | `{model.verbose_name}_list` | `Home / Posts` | [Posts Example](https://github.com/tj-django/django-view-breadcrumbs#sample-crumbs-posts) |
| `create` | [`CreateView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-editing/#createview) | `{model.verbose_name}_create` | `Home / Posts / Add Post` | |
| `detail` | [`DetailView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-display/#detailview) | `{model.verbose_name}_detail` | `Home / Posts / Test - Post` | |
| `change` | [`UpdateView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-editing/#updateview) | `{model.verbose_name}_update` | `Home / Posts / Test - Post / Update Test - Post` | |
| `delete` | [`DeleteView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-editing/#deleteview) | `{model.verbose_name}_delete` | N/A |
| N/A | [`TemplateView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/base/#templateview) | N/A | N/A | See: [Custom View](#custom-crumbs-home--my-test-breadcrumb) |
| N/A | [`FormView`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-editing/#formview) | N/A | N/A | See: [Custom View](#custom-crumbs-home--my-test-breadcrumb) |
| N/A | [`AboutView`](https://docs.djangoproject.com/en/3.2/topics/class-based-views/#subclassing-generic-views) | N/A | N/A | See: [Custom View](#custom-crumbs-home--my-test-breadcrumb) |
| N/A | [`View`](https://docs.djangoproject.com/en/3.2/ref/class-based-views/base/#view) | N/A | N/A | See: [Custom View](#custom-crumbs-home--my-test-breadcrumb) |
#### [django-tables-2](https://django-tables2.readthedocs.io/en/latest/index.html#)
| Actions | View Class | View name | Sample Breadcrumb | Example |
|-----------|-------------|-------------|-------------------|----------|
| N/A | [`SingleTableMixin`](https://django-tables2.readthedocs.io/en/latest/pages/generic-mixins.html?highlight=SingleTableMixin#a-single-table-using-singletablemixin) | N/A | N/A | See: [demo table view](https://github.com/tj-django/django-view-breadcrumbs/blob/main/demo/views.py#L154-L162) |
| N/A | [`MultiTableMixin`](https://django-tables2.readthedocs.io/en/latest/pages/generic-mixins.html?highlight=SingleTableMixin#multiple-tables-using-multitablemixin) | N/A | N/A | See: [demo table view](https://github.com/tj-django/django-view-breadcrumbs/blob/main/demo/views.py#L166-L173) |
| N/A | [`SingleTableView`](https://django-tables2.readthedocs.io/en/latest/pages/api-reference.html?highlight=SingleTableView#singletableview) | N/A | N/A | Same implementation as `SingleTableMixin` |
For more examples see: [demo app](https://github.com/tj-django/django-view-breadcrumbs/tree/main/demo)
### URL Configuration
Based on the table of actions listed above there's a strict `view_name` requirement that needs to be adhered to in order for breadcrumbs to work.
This can be manually entered in your `urls.py` or you can optionally use the following class properties instead of hardcoding the `view_name`.
```python
...
path("tests/", TestListsView.as_view(), name=TestListsView.list_view_name),
path(
"tests//",
TestDetailView.as_view(),
name=TestDetailView.detail_view_name,
),
path(
"tests//update/",
TestUpdateView.as_view(),
name=TestUpdateView.update_view_name,
),
path(
"tests//delete/",
TestDeleteView.as_view(),
name=TestDeleteView.delete_view_name,
),
...
```
### Examples
#### Sample crumbs: `Posts`
In your urls.py
```python
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`
```python
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
```
#### Sample crumbs: `Home / Posts / Test - Post`
In your `urls.py`
```python
urlpatterns = [
...
path("posts//", views.PostDetail.as_view(), name="post_detail"),
...
# OR
...
path("posts//", views.PostDetail.as_view(), name=views.PostDetail.detail_view_name),
...
]
```
`views.py`
```python
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
```
#### Custom crumbs: `Home / My Test Breadcrumb`
URL configuration.
```python
urlpatterns = [
path("my-custom-view/", views.CustomView.as_view(), name="custom_view"),
]
```
views.py
```python
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**
```python
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"))]
```
> Refer to the [demo app](https://github.com/tj-django/django-view-breadcrumbs/tree/main/demo) for more examples.
### Using multiple apps
To reference models from a different application you need to override the `app_name` class attribute.
Example:
Using a `Library` model that is imported from a `custom` application that you want to render in a `demo` app view.
```python
INSTALLED_APPS = [
...
"demo",
"custom",
...
]
```
`demo/views.py`
```python
class LibraryDetailView(DetailBreadcrumbMixin, DetailView):
model = Library
app_name = "demo"
...
```
## Running locally
```bash
$ git clone [email protected]:tj-django/django-view-breadcrumbs.git
$ 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](https://github.com/prymitive/bootstrap-breadcrumbs)
To file a bug or submit a patch, please head over to [django-view-breadcrumbs on github](https://github.com/tj-django/django-view-breadcrumbs/issues).
If you feel generous and want to show some extra appreciation:
Support me with a :star:
[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
[buymeacoffee]: https://www.buymeacoffee.com/jackton1
[buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
