Settings reference

You can override some of wagtailmenus’ default behaviour by adding one of more of the following to your project’s settings.

Admin / UI settings

WAGTAILMENUS_ADD_EDITOR_OVERRIDE_STYLES

Default value: True

By default, wagtailmenus adds some additional styles to improve the readability of the forms on the menu management pages in the Wagtail admin area. If for some reason you don’t want to override any styles, you can disable this behaviour by setting to False.

WAGTAILMENUS_FLATMENU_MENU_ICON

Default value: 'list-ol'

Use this to change the icon used to represent ‘Flat menus’ in the Wagtail CMS.

WAGTAILMENUS_FLAT_MENUS_HANDLE_CHOICES

Default value: None

Can be set to a tuple of choices in the standard Django choices format to change the presentation of the FlatMenu.handle field from a text field, to a select field with fixed choices, when adding, editing or copying a flat menus in Wagtail’s CMS.

For example, if your project uses an ‘info’ menu in the header, a ‘footer’ menu in the footer, and a ‘help’ menu in the sidebar, you could do the following:

# e.g. settings/base.py

WAGTAILMENUS_FLAT_MENUS_HANDLE_CHOICES = (
    ('info', 'Info'),
    ('help', 'Help'),
    ('footer', 'Footer'),
)

WAGTAILMENUS_FLAT_MENUS_EDITABLE_IN_WAGTAILADMIN

Default value: True

By default, ‘Flat menus’ are editable in the Wagtail CMS. Setting this to False in your project’s settings will disable this functionality, and remove the Flat menus item from Wagtail’s Settings menu.

WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS

Default value: 'wagtailmenus.modeladmin.FlatMenuAdmin'

If you wish to override the ModelAdmin class used to represent ‘Flat menus’ in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.

# e.g. settings/base.py

WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS = "projectname.appname.modulename.ClassName"

The value should be an import path string, rather than a direct pointer to the class itself. wagtailmenus will lazily import the class from this path when it is required. If the path is invalid, an ImproperlyConfigured exception will be raised.

WAGTAILMENUS_MAINMENU_MENU_ICON

Default value: 'list-ol'

Use this to change the icon used to represent ‘Main menus’ in the Wagtail CMS.

WAGTAILMENUS_MAIN_MENUS_EDITABLE_IN_WAGTAILADMIN

Default value: True

By default, ‘Main menus’ are editable in the Wagtail CMS. Setting this to False in your project’s settings will disable this functionality, and remove the Main menus item from Wagtail’s Settings menu.

WAGTAILMENUS_MAIN_MENUS_MODELADMIN_CLASS

Default value: 'wagtailmenus.modeladmin.MainMenuAdmin'

If you wish to override the ModelAdmin class used to represent ‘Main menus’ in the Wagtail admin area for your project (e.g. to display additional custom fields in the listing view, or change/add new views), you can do so by using this setting to swap out the default class for a custom one. e.g.

# e.g. settings/base.py

WAGTAILMENUS_MAIN_MENUS_MODELADMIN_CLASS = "projectname.appname.modulename.ClassName"

The value should be an import path string, rather than a direct pointer to the class itself. Wagtailmenus will lazily import the class from this path when it is required. If the path is invalid, and ImproperlyConfigured exception will be raised.

Default templates and template finder settings

WAGTAILMENUS_DEFAULT_CHILDREN_MENU_TEMPLATE

Default value: 'menus/children_menu.html'

The name of the template used for rendering by the {% children_menu %} tag when no other template has been specified using the template parameter.

WAGTAILMENUS_DEFAULT_FLAT_MENU_TEMPLATE

Default value: 'menus/flat_menu.html'

The name of the template used for rendering by the {% flat_menu %} tag when no other template has been specified using the template parameter.

WAGTAILMENUS_DEFAULT_MAIN_MENU_TEMPLATE

Default value: 'menus/main_menu.html'

The name of the template used for rendering by the {% main_menu %} tag when no other template has been specified using the template parameter.

WAGTAILMENUS_DEFAULT_SECTION_MENU_TEMPLATE

Default value: 'menus/section_menu.html'

The name of the template used for rendering by the {% section_menu %} tag when no other template has been specified using the template parameter.

WAGTAILMENUS_DEFAULT_SUB_MENU_TEMPLATE

Default value: 'menus/sub_menu.html'

The name of the template used for rendering by the {% sub_menu %} tag when no other template has been specified using the template parameter or using the sub_menu_template parameter on the original menu tag.

WAGTAILMENUS_SITE_SPECIFIC_TEMPLATE_DIRS

Default value: False

If you have a multi-site project, and want to be able to use different templates for some or all of those sites, wagtailmenus can be configured to look for additional ‘site specific’ paths for each template. To enable this feature, you add the following to your project’s settings:

# e.g. settings/base.py

WAGTAILMENUS_SITE_SPECIFIC_TEMPLATE_DIRS = True

With this set, menu tags will attempt to identify the relevant wagtail.core.models.Site instance for the current request. Wagtailmenus will then look for template names with the domain value of that Site object in their path.

For more information about where wagtailmenus looks for templates, see: Using preferred paths and names for your templates

Default tag behaviour settings

WAGTAILMENUS_FLAT_MENUS_FALL_BACK_TO_DEFAULT_SITE_MENUS

Default value: False

The default value used for fall_back_to_default_site_menus option of the {% flat_menu %} tag when a parameter value isn’t provided.

WAGTAILMENUS_GUESS_TREE_POSITION_FROM_PATH

Default value: True

When not using wagtail’s routing/serving mechanism to serve page objects, wagtailmenus can use the request path to attempt to identify a ‘current’ page, ‘section root’ page, allowing {% section_menu %} and active item highlighting to work. If this functionality is not required for your project, you can disable it by setting this value to False.

WAGTAILMENUS_DEFAULT_ADD_SUB_MENUS_INLINE

New in version 2.12.

Default value: False

For all menu types, when preparing menu items for rendering, sub menus are not added to menu items directly by default, because it’s more common for developers to use the {% sub_menu %} tag in a menu templates to render additional branches of the menu. In which case, the sub menu is created by the tag.

This behaviour can be overridden on an ‘individual use’ basis by utilising the add_sub_menus_inline option available for each template tag. However, users wishing to change the default behaviour (so that sub menus are appended directly to menu items, without having to specify) can do so by providing a value of True in their project settings.

WAGTAILMENUS_DEFAULT_CHILDREN_MENU_MAX_LEVELS

Default value: 1

The maximum number of levels rendered by the {% children_menu %} tag when no value has been specified using the max_levels parameter.

WAGTAILMENUS_DEFAULT_SECTION_MENU_MAX_LEVELS

Default value: 2

The maximum number of levels rendered by the {% section_menu %} tag when no value has been specified using the max_levels parameter.

Miscellaneous settings

WAGTAILMENUS_ACTIVE_CLASS

Default value: 'active'

The class added to menu items for the currently active page (when using a menu template with apply_active_classes=True)

WAGTAILMENUS_ACTIVE_ANCESTOR_CLASS

Default value: 'ancestor'

The class added to any menu items for pages that are ancestors of the currently active page (when using a menu template with apply_active_classes=True)

WAGTAILMENUS_PAGE_FIELD_FOR_MENU_ITEM_TEXT

Default value: 'title'

When preparing menu items for rendering, wagtailmenus looks for a field, attribute or property method on each page with this name to set a text attribute value, which is used in menu templates as the label for each item. The title field is used by default.

Note

wagtailmenus will only be able to access custom page fields or methods if ‘specific’ pages are being used. If no attribute can be found matching the specified name, wagtailmenus will silently fall back to using the page’s title field value.

WAGTAILMENUS_SECTION_ROOT_DEPTH

Default value: 3

Use this to specify the ‘depth’ value of a project’s ‘section root’ pages. For most Wagtail projects, this should be 3 (Root page depth = 1, Home page depth = 2), but it may well differ, depending on the needs of the project.

WAGTAILMENUS_CUSTOM_URL_SMART_ACTIVE_CLASSES

Default value: False

By default, menu items linking to custom URLs are attributed with the ‘active’ class only if their link_url value matches the path of the current request _exactly_. Setting this to True in your project’s settings will enable a smarter approach to active class attribution for custom URLs, where only the ‘path’ part of the link_url value is used to determine what active class should be used. The new approach will also attribute the ‘ancestor’ class to menu items if the link_url looks like an ancestor of the current request URL.