0
# Models
1

2
Core model classes for creating and managing menu structures in WagtailMenus. This includes menu container models, individual menu item models, and utility functions for accessing the configured models.
3

4
## Capabilities
5

6
### Model Access Functions
7

8
Functions to access the configured menu models, allowing for customization through Django settings while maintaining compatibility.
9

10
```python { .api }
11
def get_main_menu_model_string():
12
    """
13
    Get the dotted app.Model name for the main menu model as a string.
14
    
15
    Returns:
16
        str: Dotted model name (e.g., 'wagtailmenus.MainMenu')
17
    """
18

19
def get_flat_menu_model_string():
20
    """
21
    Get the dotted app.Model name for the flat menu model as a string.
22
    
23
    Returns:
24
        str: Dotted model name (e.g., 'wagtailmenus.FlatMenu')
25
    """
26

27
def get_main_menu_model():
28
    """
29
    Get the actual main menu model class.
30
    
31
    Returns:
32
        type: Main menu model class (default: MainMenu)
33
    """
34

35
def get_flat_menu_model():
36
    """
37
    Get the actual flat menu model class.
38
    
39
    Returns:
40
        type: Flat menu model class (default: FlatMenu)
41
    """
42
```
43

44
### Base Menu Classes
45

46
Abstract base classes that define the core menu functionality and can be extended for custom menu implementations.
47

48
```python { .api }
49
class MenuItem:
50
    """Base class for all menu item classes."""
51
    
52
class Menu:
53
    """Base class for all menu classes."""
54
    
55
class MenuFromPage(Menu):
56
    """Menu whose items descend from a specific page."""
57
    
58
class MenuWithMenuItems(Menu):
59
    """Menu with menu item model instances."""
60
```
61

62
### Menu Models
63

64
Concrete menu models for managing navigation structures in Wagtail sites.
65

66
```python { .api }
67
class AbstractMainMenu:
68
    """Abstract base model for main menus."""
69
    
70
class MainMenu(AbstractMainMenu):
71
    """
72
    Concrete main menu model for site-wide navigation.
73
    
74
    Used for primary navigation menus that appear on all or most pages.
75
    Automatically integrates with Wagtail's Site model for multi-site support.
76
    """
77
    
78
    def render_from_tag(context, max_levels=None, **kwargs):
79
        """Render menu from template tag with context."""
80
        
81
class AbstractFlatMenu:
82
    """Abstract base model for flat menus."""
83
    
84
class FlatMenu(AbstractFlatMenu):
85
    """
86
    Concrete flat menu model for custom navigation menus.
87
    
88
    Used for secondary menus like footers, sidebars, or special navigation
89
    sections. Each flat menu is identified by a unique handle.
90
    """
91
    
92
    handle: str  # Unique identifier for the menu
93
    
94
    def render_from_tag(context, handle, **kwargs):
95
        """Render menu from template tag with handle and context."""
96
        
97
class SectionMenu:
98
    """Section navigation menu for showing page hierarchy context."""
99
    
100
    def render_from_tag(context, **kwargs):
101
        """Render section menu from template tag."""
102
        
103
class ChildrenMenu:
104
    """Child page menu for displaying sub-pages of current page."""
105
    
106
    def render_from_tag(context, **kwargs):
107
        """Render children menu from template tag."""
108
        
109
class SubMenu:
110
    """Sub-menu implementation for nested menu structures."""
111
    
112
    def render_from_tag(context, **kwargs):
113
        """Render sub-menu from template tag."""
114
```
115

116
### Menu Item Models
117

118
Models representing individual items within menus, supporting various link types and hierarchical structures.
119

120
```python { .api }
121
class AbstractMenuItem:
122
    """Abstract base model for menu items."""
123
    
124
    link_page: 'Page'  # Optional page to link to
125
    link_url: str      # Optional external URL
126
    link_text: str     # Display text for the item
127
    url_append: str    # Optional hash or querystring to append
128
    handle: str        # Optional identifier for custom templating
129
    allow_subnav: bool # Whether to show child pages as sub-menu
130
    
131
    @property
132
    def menu_text(self) -> str:
133
        """Get the display text for this menu item."""
134
    
135
    def relative_url(self, site=None, request=None) -> str:
136
        """Get the relative URL for this menu item."""
137
    
138
    def get_full_url(self, request=None) -> str:
139
        """Get the absolute URL for this menu item."""
140
    
141
    def get_active_class_for_request(self, request=None) -> str:
142
        """Get CSS class for active state based on request."""
143
    
144
class AbstractMainMenuItem(AbstractMenuItem):
145
    """Abstract model for main menu items."""
146
    
147
class MainMenuItem(AbstractMainMenuItem):
148
    """
149
    Concrete main menu item model.
150
    
151
    Represents individual items in main menus with support for
152
    linking to pages, external URLs, and hierarchical sub-menus.
153
    """
154
    
155
    menu: MainMenu  # Parent menu
156
    sort_order: int # Ordering within menu
157
    
158
class AbstractFlatMenuItem(AbstractMenuItem):
159
    """Abstract model for flat menu items."""
160
    
161
class FlatMenuItem(AbstractFlatMenuItem):
162
    """
163
    Concrete flat menu item model.
164
    
165
    Represents individual items in flat menus with the same
166
    linking capabilities as main menu items.
167
    """
168
    
169
    menu: FlatMenu  # Parent menu
170
    sort_order: int # Ordering within menu
171
```
172

173
### Menu Item Manager
174

175
Custom manager for menu item querysets with additional functionality.
176

177
```python { .api }
178
class MenuItemManager:
179
    """Custom manager for menu items with enhanced querying capabilities."""
180
    
181
    def for_display():
182
        """Return items suitable for display (published, etc.)."""
183
```
184

185
## Usage Examples
186

187
### Creating and Using Main Menus
188

189
```python
190
from wagtailmenus import get_main_menu_model
191
from wagtail.models import Site
192

193
# Get the configured main menu model
194
MainMenu = get_main_menu_model()
195

196
# Create a main menu for a site
197
site = Site.objects.get(is_default_site=True)
198
main_menu = MainMenu.objects.create(site=site)
199

200
# Add menu items programmatically
201
from wagtailmenus.models import MainMenuItem
202
from myapp.models import HomePage
203

204
home_page = HomePage.objects.first()
205
MainMenuItem.objects.create(
206
    menu=main_menu,
207
    link_page=home_page,
208
    link_text="Home",
209
    sort_order=1
210
)
211
```
212

213
### Creating Flat Menus
214

215
```python
216
from wagtailmenus import get_flat_menu_model
217

218
FlatMenu = get_flat_menu_model()
219

220
# Create a footer menu
221
footer_menu = FlatMenu.objects.create(
222
    site=site,
223
    title="Footer Navigation",
224
    handle="footer-menu",
225
    heading="Quick Links"
226
)
227

228
# Add items to flat menu
229
from wagtailmenus.models import FlatMenuItem
230

231
FlatMenuItem.objects.create(
232
    menu=footer_menu,
233
    link_text="About Us",
234
    link_url="/about/",
235
    sort_order=1
236
)
237
```
238

239
### Working with Abstract Models
240

241
```python
242
# For custom menu implementations, extend abstract models
243
from wagtailmenus.models import AbstractMainMenu
244

245
class CustomMainMenu(AbstractMainMenu):
246
    custom_field = models.CharField(max_length=100)
247
    
248
    class Meta:
249
        verbose_name = "Custom Main Menu"
250
```
251

252
## Types
253

254
```python { .api }
255
# Django model field types used in menu models
256
class MenuModels:
257
    link_page: 'wagtail.models.Page'
258
    link_url: str
259
    link_text: str
260
    allow_subnav: bool
261
    sort_order: int
262
    handle: str
263
```