repository·master·Indexed 19 days ago
https://github.com/jazzband/wagtailmenusA Wagtail CMS extension for managing and rendering multi-level and flat navigation menus. It provides tools for creating link pages via AbstractLinkPage and offers extensibility through abstract models like AbstractMainMenu, AbstractMainMenuItem, AbstractFlatMenu, and AbstractFlatMenuItem to allow custom fields and logic in menu structures.
The AbstractLinkPage model is an abstract model designed to allow editors to add additional links to menus by adding pages to the Wagtail page tree.
This is useful because standard 'main' and 'flat' menus only allow editors to define top-level items. By using AbstractLinkPage, editors can create link pages that point to other Wagtail pages or custom URLs.
Key behaviors:
Normally, in a multi-level menu, a parent item acts as a toggle. If you want an important page to appear as a clickable link and also act as a parent for a sub-menu, extend the wagtailmenus.models.MenuPage model instead of the standard wagtail.core.models.Page model.
This provides extra fields that allow the item to repeat in the rendered menu, ensuring it doesn't just become a non-clickable 'toggle'.
When defining menu items, you are not limited to standard page links. You can use the custom URL field to:
#signup or #request-callback).Wagtailmenus supports multi-site setups through several strategies for flat menus:
Key features for multi-site users:
custom_templates_auto).fall_back_to_default_site_menus option to control behavior when a site-specific menu is missing.Even if a page is a child of a menu item with allow_subnav=True, it will only appear in the rendered menu if its show_in_menus attribute is True.
To exclude specific page types from appearing in menus by default (e.g., news articles or events that should only appear on listing pages), set the show_in_menus_default attribute to False on your page type class:
class NewsArticlePage(Page):
show_in_menus_default = False
# ... other fieldsWhen a page model subclasses MenuPage or MenuPageMixin, it receives special treatment from the wagtailmenus template tags. This allows you to programmatically add, remove, or modify sub-menu items that appear below that specific page in a menu.
To implement custom sub-menu logic, you must override two methods:
modify_submenu_items(self, menu_items, **kwargs): Used to add or alter the list of menu items. You should always call super().modify_submenu_items(menu_items, **kwargs) first to ensure default behavior (like repeating links) is preserved.has_submenu_items(self, **kwargs): Used to tell the menu template whether this page should render a dropdown/submenu. If you are adding items manually via modify_submenu_items, you often need to override this to return True even if the page has no child pages.Important Note: If you override modify_submenu_items, ensure that 'repeated menu items' remain the first item in the returned list to prevent issues with active class highlighting.
class MyPage(MenuPage):
def modify_submenu_items(self, menu_items, **kwargs):
menu_items = super().modify_submenu_items(menu_items, **kwargs)
# Add custom items here
return menu_items
def has_submenu_items(self, **kwargs):
return TrueBeyond the main navigation, you can create any number of additional menus (like footers or secondary headers) via the CMS as 'flat menus'.
Flat menus are managed independently in the CMS, allowing editors to make 'emergency changes' or 'last-minute tweaks' without code deployments. Although called 'flat', they can still be configured to render as multi-level menus if required.
You can customize the behavior of nested menus using specific arguments within the {% sub_menu %} tag:
use_absolute_page_urls: Set to True to use absolute URLs for href attributes instead of relative ones.template: Pass a string representing a template path to override the default sub-menu template (which is normally controlled by sub_menu_template in the context).apply_active_classes: Override whether active CSS classes are applied.allow_repeating_parents: Override whether parent items are allowed to repeat in the menu structure.In multi-level menus, parent pages often act only as toggles to show/hide children, making the parent page itself inaccessible.
By using MenuPage or MenuPageMixin, you can enable a feature called Repeat in sub-navigation. When enabled, an additional link is rendered alongside the children in the menu, allowing users to access the parent page directly.
You can customize the text for this repeated link using the Repeated item link text field in the page settings. The menu tags are designed to handle 'active' classes intelligently: when viewing the parent page, the repeated item is marked as 'active' while the original parent link is marked as 'ancestor' to maintain consistent styling.
Wagtailmenus uses a hybrid approach to menu structure:
allow_subnav=True is set, the library dynamically generates the sub-menu structure based on your existing Wagtail page tree.This ensures that while you control the main navigation entry points, the sub-navigation automatically stays in sync with the natural order and structure of your page tree, reducing manual maintenance when pages are moved or reordered.
wagtailmenus is an extension for Wagtail CMS designed to help you define, manage, and render menus. To begin using the project, follow these primary paths:
installation guide to add the package to your Wagtail project.managing_main_menus (for hierarchical structures) or managing_flat_menus (for simpler structures).MenuPage or AbstractLinkPage to integrate menu management directly into your Wagtail page tree.