or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

administration.mdconfiguration.mdindex.mdmodels.mdpage-integration.mdtemplate-tags.md
tile.json

tessl/pypi-wagtailmenus

An app to help you manage menus in your Wagtail projects more consistently.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/wagtailmenus@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-wagtailmenus@4.0.0

index.mddocs/

WagtailMenus

A comprehensive Django/Wagtail CMS extension that provides a robust framework for managing and rendering hierarchical navigation menus and flat menus in web applications. WagtailMenus offers flexible menu management capabilities including multi-level navigation structures, customizable menu items with advanced linking options, template tags for consistent menu rendering across different page types, and administrative interfaces for content managers to easily create and maintain site navigation.

Package Information

  • Package Name: wagtailmenus
  • Language: Python
  • Installation: pip install wagtailmenus
  • Minimum Requirements: Django 4.2+, Wagtail 6.3+, Python 3.9+

Core Imports

# Main package utilities
import wagtailmenus
from wagtailmenus import get_main_menu_model, get_flat_menu_model

Common model imports:

# Menu models
from wagtailmenus.models import MainMenu, FlatMenu, SectionMenu, ChildrenMenu

# Menu item models  
from wagtailmenus.models import MainMenuItem, FlatMenuItem

# Page mixins for menu functionality
from wagtailmenus.models import MenuPageMixin, MenuPage, AbstractLinkPage

Template tags (in Django templates):

{% load menu_tags %}

Basic Usage

Setting up Menus in Django Settings

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'wagtailmenus',
    # ... rest of apps
]

# Add context processor for template access
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'context_processors': [
                # ... other processors
                'wagtailmenus.context_processors.wagtailmenus',
            ],
        },
    },
]

Using Template Tags

<!-- Load template tags -->
{% load menu_tags %}

<!-- Render main navigation menu -->
{% main_menu max_levels=3 template='menus/main_menu.html' %}

<!-- Render a flat menu by handle -->
{% flat_menu 'footer-menu' max_levels=1 template='menus/flat_menu.html' %}

<!-- Render section navigation -->
{% section_menu show_section_root=True max_levels=2 %}

<!-- Render child pages menu -->
{% children_menu %}

Creating Custom Menu Pages

from wagtailmenus.models import MenuPageMixin
from wagtail.models import Page

class CustomPage(MenuPageMixin, Page):
    # Your page fields
    content_panels = Page.content_panels + [
        # Your panels
    ]
    
    # Menu settings will be automatically available
    settings_panels = Page.settings_panels + MenuPageMixin.menu_settings_panels

Architecture

WagtailMenus follows a hierarchical architecture designed around Django models and Wagtail's page tree:

  • Menu Models: Core menu containers (MainMenu, FlatMenu) that hold configuration
  • MenuItem Models: Individual menu items that can link to pages, URLs, or sub-menus
  • Page Mixins: Extensions for Wagtail pages to integrate with menu system
  • Template Tags: Rendering engine that converts models to HTML with context awareness
  • Admin Interfaces: Wagtail admin integration for menu management

The system supports both automatic menu generation from page trees and manual menu creation with full customization.

Capabilities

Model API

Core model classes for creating and managing menu structures, including base menu models, menu item models, and page mixins for integration with Wagtail's page system.

# Core model access functions
def get_main_menu_model(): ...
def get_flat_menu_model(): ...

# Base model classes  
class MainMenu: ...
class FlatMenu: ...
class MainMenuItem: ...
class FlatMenuItem: ...

Models

Template Tags

Django template tags for rendering menus in templates with extensive customization options for styling, levels, active states, and template selection.

# Main template tags
def main_menu(
    context, max_levels=None, apply_active_classes=True,
    allow_repeating_parents=True, show_multiple_levels=True,
    template='', sub_menu_template='', sub_menu_templates=None,
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
): ...

def flat_menu(
    context, handle, max_levels=None, show_menu_heading=True,
    apply_active_classes=False, allow_repeating_parents=True,
    show_multiple_levels=True, template='', sub_menu_template='',
    sub_menu_templates=None, fall_back_to_default_site_menus=None,
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
): ...

def section_menu(
    context, show_section_root=True, show_multiple_levels=True,
    apply_active_classes=True, allow_repeating_parents=True,
    max_levels=2, template='', sub_menu_template='',
    sub_menu_templates=None, use_absolute_page_urls=False,
    add_sub_menus_inline=None, **kwargs
): ...

def children_menu(
    context, parent_page=None, allow_repeating_parents=True,
    apply_active_classes=False, max_levels=1, template='',
    sub_menu_template='', sub_menu_templates=None,
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
): ...

def sub_menu(
    context, menuitem_or_page, allow_repeating_parents=None,
    apply_active_classes=None, template='', use_absolute_page_urls=None,
    add_sub_menus_inline=None, **kwargs
): ...

Template Tags

Page Integration

Mixins and base classes for integrating Wagtail pages with the menu system, enabling pages to participate in navigation structures and control their menu behavior.

class MenuPageMixin: ...
class MenuPage(MenuPageMixin, Page): ...
class AbstractLinkPage: ...

Page Integration

Administration

Admin interfaces and form classes for managing menus through Wagtail's admin interface, including inline panels for menu items and configuration forms.

class MainMenuAdmin: ...
class FlatMenuAdmin: ...
class MenuItemInlinePanel: ...

Administration

Configuration & Settings

Settings management, configuration helpers, and utility functions for customizing wagtailmenus behavior across your Django project.

class WagtailmenusSettingsHelper: ...
# Configuration constants and defaults
MAX_LEVELS_CHOICES: tuple

Configuration

Types

# Version information
VERSION: tuple[int, int, int, str, int]
__version__: str

# Settings constants
MAX_LEVELS_CHOICES: tuple[tuple[int, str], ...]