0
# WagtailMenus
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: wagtailmenus
7
- **Language**: Python
8
- **Installation**: `pip install wagtailmenus`
9
- **Minimum Requirements**: Django 4.2+, Wagtail 6.3+, Python 3.9+
10

11
## Core Imports
12

13
```python
14
# Main package utilities
15
import wagtailmenus
16
from wagtailmenus import get_main_menu_model, get_flat_menu_model
17
```
18

19
Common model imports:
20

21
```python
22
# Menu models
23
from wagtailmenus.models import MainMenu, FlatMenu, SectionMenu, ChildrenMenu
24

25
# Menu item models  
26
from wagtailmenus.models import MainMenuItem, FlatMenuItem
27

28
# Page mixins for menu functionality
29
from wagtailmenus.models import MenuPageMixin, MenuPage, AbstractLinkPage
30
```
31

32
Template tags (in Django templates):
33

34
```django
35
{% load menu_tags %}
36
```
37

38
## Basic Usage
39

40
### Setting up Menus in Django Settings
41

42
```python
43
# settings.py
44
INSTALLED_APPS = [
45
    # ... other apps
46
    'wagtailmenus',
47
    # ... rest of apps
48
]
49

50
# Add context processor for template access
51
TEMPLATES = [
52
    {
53
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
54
        'OPTIONS': {
55
            'context_processors': [
56
                # ... other processors
57
                'wagtailmenus.context_processors.wagtailmenus',
58
            ],
59
        },
60
    },
61
]
62
```
63

64
### Using Template Tags
65

66
```django
67
<!-- Load template tags -->
68
{% load menu_tags %}
69

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

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

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

79
<!-- Render child pages menu -->
80
{% children_menu %}
81
```
82

83
### Creating Custom Menu Pages
84

85
```python
86
from wagtailmenus.models import MenuPageMixin
87
from wagtail.models import Page
88

89
class CustomPage(MenuPageMixin, Page):
90
    # Your page fields
91
    content_panels = Page.content_panels + [
92
        # Your panels
93
    ]
94
    
95
    # Menu settings will be automatically available
96
    settings_panels = Page.settings_panels + MenuPageMixin.menu_settings_panels
97
```
98

99
## Architecture
100

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

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

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

111
## Capabilities
112

113
### Model API
114

115
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.
116

117
```python { .api }
118
# Core model access functions
119
def get_main_menu_model(): ...
120
def get_flat_menu_model(): ...
121

122
# Base model classes  
123
class MainMenu: ...
124
class FlatMenu: ...
125
class MainMenuItem: ...
126
class FlatMenuItem: ...
127
```
128

129
[Models](./models.md)
130

131
### Template Tags
132

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

135
```python { .api }
136
# Main template tags
137
def main_menu(
138
    context, max_levels=None, apply_active_classes=True,
139
    allow_repeating_parents=True, show_multiple_levels=True,
140
    template='', sub_menu_template='', sub_menu_templates=None,
141
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
142
): ...
143

144
def flat_menu(
145
    context, handle, max_levels=None, show_menu_heading=True,
146
    apply_active_classes=False, allow_repeating_parents=True,
147
    show_multiple_levels=True, template='', sub_menu_template='',
148
    sub_menu_templates=None, fall_back_to_default_site_menus=None,
149
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
150
): ...
151

152
def section_menu(
153
    context, show_section_root=True, show_multiple_levels=True,
154
    apply_active_classes=True, allow_repeating_parents=True,
155
    max_levels=2, template='', sub_menu_template='',
156
    sub_menu_templates=None, use_absolute_page_urls=False,
157
    add_sub_menus_inline=None, **kwargs
158
): ...
159

160
def children_menu(
161
    context, parent_page=None, allow_repeating_parents=True,
162
    apply_active_classes=False, max_levels=1, template='',
163
    sub_menu_template='', sub_menu_templates=None,
164
    use_absolute_page_urls=False, add_sub_menus_inline=None, **kwargs
165
): ...
166

167
def sub_menu(
168
    context, menuitem_or_page, allow_repeating_parents=None,
169
    apply_active_classes=None, template='', use_absolute_page_urls=None,
170
    add_sub_menus_inline=None, **kwargs
171
): ...
172
```
173

174
[Template Tags](./template-tags.md)
175

176
### Page Integration
177

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

180
```python { .api }
181
class MenuPageMixin: ...
182
class MenuPage(MenuPageMixin, Page): ...
183
class AbstractLinkPage: ...
184
```
185

186
[Page Integration](./page-integration.md)
187

188
### Administration
189

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

192
```python { .api }
193
class MainMenuAdmin: ...
194
class FlatMenuAdmin: ...
195
class MenuItemInlinePanel: ...
196
```
197

198
[Administration](./administration.md)
199

200
### Configuration & Settings
201

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

204
```python { .api }
205
class WagtailmenusSettingsHelper: ...
206
# Configuration constants and defaults
207
MAX_LEVELS_CHOICES: tuple
208
```
209

210
[Configuration](./configuration.md)
211

212
## Types
213

214
```python { .api }
215
# Version information
216
VERSION: tuple[int, int, int, str, int]
217
__version__: str
218

219
# Settings constants
220
MAX_LEVELS_CHOICES: tuple[tuple[int, str], ...]
221
```