tessl/pypi-wagtailmenus
An app to help you manage menus in your Wagtail projects more consistently.
models.mddocs/
Models
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.
Capabilities
Model Access Functions
Functions to access the configured menu models, allowing for customization through Django settings while maintaining compatibility.
def get_main_menu_model_string():
"""
Get the dotted app.Model name for the main menu model as a string.
Returns:
str: Dotted model name (e.g., 'wagtailmenus.MainMenu')
"""
def get_flat_menu_model_string():
"""
Get the dotted app.Model name for the flat menu model as a string.
Returns:
str: Dotted model name (e.g., 'wagtailmenus.FlatMenu')
"""
def get_main_menu_model():
"""
Get the actual main menu model class.
Returns:
type: Main menu model class (default: MainMenu)
"""
def get_flat_menu_model():
"""
Get the actual flat menu model class.
Returns:
type: Flat menu model class (default: FlatMenu)
"""Base Menu Classes
Abstract base classes that define the core menu functionality and can be extended for custom menu implementations.
class MenuItem:
"""Base class for all menu item classes."""
class Menu:
"""Base class for all menu classes."""
class MenuFromPage(Menu):
"""Menu whose items descend from a specific page."""
class MenuWithMenuItems(Menu):
"""Menu with menu item model instances."""Menu Models
Concrete menu models for managing navigation structures in Wagtail sites.
class AbstractMainMenu:
"""Abstract base model for main menus."""
class MainMenu(AbstractMainMenu):
"""
Concrete main menu model for site-wide navigation.
Used for primary navigation menus that appear on all or most pages.
Automatically integrates with Wagtail's Site model for multi-site support.
"""
def render_from_tag(context, max_levels=None, **kwargs):
"""Render menu from template tag with context."""
class AbstractFlatMenu:
"""Abstract base model for flat menus."""
class FlatMenu(AbstractFlatMenu):
"""
Concrete flat menu model for custom navigation menus.
Used for secondary menus like footers, sidebars, or special navigation
sections. Each flat menu is identified by a unique handle.
"""
handle: str # Unique identifier for the menu
def render_from_tag(context, handle, **kwargs):
"""Render menu from template tag with handle and context."""
class SectionMenu:
"""Section navigation menu for showing page hierarchy context."""
def render_from_tag(context, **kwargs):
"""Render section menu from template tag."""
class ChildrenMenu:
"""Child page menu for displaying sub-pages of current page."""
def render_from_tag(context, **kwargs):
"""Render children menu from template tag."""
class SubMenu:
"""Sub-menu implementation for nested menu structures."""
def render_from_tag(context, **kwargs):
"""Render sub-menu from template tag."""Menu Item Models
Models representing individual items within menus, supporting various link types and hierarchical structures.
class AbstractMenuItem:
"""Abstract base model for menu items."""
link_page: 'Page' # Optional page to link to
link_url: str # Optional external URL
link_text: str # Display text for the item
url_append: str # Optional hash or querystring to append
handle: str # Optional identifier for custom templating
allow_subnav: bool # Whether to show child pages as sub-menu
@property
def menu_text(self) -> str:
"""Get the display text for this menu item."""
def relative_url(self, site=None, request=None) -> str:
"""Get the relative URL for this menu item."""
def get_full_url(self, request=None) -> str:
"""Get the absolute URL for this menu item."""
def get_active_class_for_request(self, request=None) -> str:
"""Get CSS class for active state based on request."""
class AbstractMainMenuItem(AbstractMenuItem):
"""Abstract model for main menu items."""
class MainMenuItem(AbstractMainMenuItem):
"""
Concrete main menu item model.
Represents individual items in main menus with support for
linking to pages, external URLs, and hierarchical sub-menus.
"""
menu: MainMenu # Parent menu
sort_order: int # Ordering within menu
class AbstractFlatMenuItem(AbstractMenuItem):
"""Abstract model for flat menu items."""
class FlatMenuItem(AbstractFlatMenuItem):
"""
Concrete flat menu item model.
Represents individual items in flat menus with the same
linking capabilities as main menu items.
"""
menu: FlatMenu # Parent menu
sort_order: int # Ordering within menuMenu Item Manager
Custom manager for menu item querysets with additional functionality.
class MenuItemManager:
"""Custom manager for menu items with enhanced querying capabilities."""
def for_display():
"""Return items suitable for display (published, etc.)."""Usage Examples
Creating and Using Main Menus
from wagtailmenus import get_main_menu_model
from wagtail.models import Site
# Get the configured main menu model
MainMenu = get_main_menu_model()
# Create a main menu for a site
site = Site.objects.get(is_default_site=True)
main_menu = MainMenu.objects.create(site=site)
# Add menu items programmatically
from wagtailmenus.models import MainMenuItem
from myapp.models import HomePage
home_page = HomePage.objects.first()
MainMenuItem.objects.create(
menu=main_menu,
link_page=home_page,
link_text="Home",
sort_order=1
)Creating Flat Menus
from wagtailmenus import get_flat_menu_model
FlatMenu = get_flat_menu_model()
# Create a footer menu
footer_menu = FlatMenu.objects.create(
site=site,
title="Footer Navigation",
handle="footer-menu",
heading="Quick Links"
)
# Add items to flat menu
from wagtailmenus.models import FlatMenuItem
FlatMenuItem.objects.create(
menu=footer_menu,
link_text="About Us",
link_url="/about/",
sort_order=1
)Working with Abstract Models
# For custom menu implementations, extend abstract models
from wagtailmenus.models import AbstractMainMenu
class CustomMainMenu(AbstractMainMenu):
custom_field = models.CharField(max_length=100)
class Meta:
verbose_name = "Custom Main Menu"Types
# Django model field types used in menu models
class MenuModels:
link_page: 'wagtail.models.Page'
link_url: str
link_text: str
allow_subnav: bool
sort_order: int
handle: strInstall with Tessl CLI
npx tessl i tessl/pypi-wagtailmenus