django-navhelper

1.0.0 verified Mon Apr 27 auth: no python

Provides Django template tags to help render navigation menus and breadcrumbs from a hierarchical structure of sections. Version 1.0.0 requires Django 4.2+ and drops support for older Django versions. Released as needed, currently stable.

pip install django-navhelper

Common errors

error TemplateDoesNotExist: navhelper/menu.html ↓

cause The navhelper templates are not available because the app's templates directory is not found. Ensure 'navhelper' is in INSTALLED_APPS.

fix

Add 'navhelper' to INSTALLED_APPS in settings.py.

error 'NoneType' object has no attribute 'children' ↓

cause The template tag expects a 'children' attribute on each node, but your model does not have it. You need to set up reverse relation (e.g., children = models.ForeignKey(...)) or pass a queryset with prefetched children.

fix

Define a model with parent ForeignKey and use prefetch_related('children') if you have a related_name set. Alternatively, add a 'children' property that returns the queryset of siblings.

Warnings

breaking Version 1.0.0 drops support for Django versions older than 4.2. Upgrade your Django version to 4.2+ before updating. ↓

fix Ensure Django >= 4.2 is installed: pip install 'django>=4.2'

gotcha The template tag expects a queryset or list of objects with 'parent' and 'children' attributes. Ensure your model has foreign key to self and a method/attribute for children (e.g., via prefetch_related). ↓

fix Use a model like Section with parent ForeignKey and define a 'children' property or use reverse relation. Example: prefetch_related('section_set') and set children attribute manually.

gotcha The navhelper_menu tag may not automatically handle active state. You might need to pass 'current' parameter or implement custom logic for highlighting current section. ↓

fix Check documentation for 'current' argument in template tag usage.

Imports

NavHelper
```
from navhelper import NavHelper
```
Main class for building navigation structures.
register_nav_tag
wrong
```
from navhelper.templatetags.navhelper import ...
```
correct
```
from navhelper.templatetags import navhelper
```
The templatetags module is imported directly; no submodule for individual tags.

Quickstart

Set up a Section model with parent hierarchy, add 'navhelper' to INSTALLED_APPS, then use the navhelper_menu template tag to render a nested menu.

# settings.py
INSTALLED_APPS = [
    ...
    'navhelper',
]

# models.py
from django.db import models
from navhelper import NavHelper

class Section(models.Model):
    title = models.CharField(max_length=100)
    slug = models.SlugField()
    parent = models.ForeignKey('self', null=True, blank=True, on_delete=models.CASCADE)
    url = models.CharField(max_length=200, blank=True)

    def __str__(self):
        return self.title

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('section/<slug:slug>/', views.section_detail, name='section_detail'),
]

# template.html
{% load navhelper %}
<ul>
{% navhelper_menu sections %}
</ul>