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:

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

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 editing ‘Main menus’ in the Wagtail CMS.

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 editing ‘Flat menus’ in the Wagtail CMS.

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:

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_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.

WAGTAILMENUS_DEFAULT_CHILDREN_MENU_USE_SPECIFIC

Default value: 1 (Auto)

Controls how ‘specific’ pages objects are fetched and used during rendering of the {% children_menu %} tag when no use_specific value isn’t supplied.

If you’d like to use custom page fields in your children menus (e.g. translated field values or image fields) or if your page models override get_url_parts(), relative_url() or other Page methods involved in URL generation, you’ll likely want to update this.

To find out more about what values are supported and the effect they have, see: ‘Specific’ pages and menus

WAGTAILMENUS_DEFAULT_SECTION_MENU_USE_SPECIFIC

Default value: 1 (Auto)

Controls how ‘specific’ pages objects are fetched and used during rendering of the {% section_menu %} tag when no alternative value has been specified using the use_specific parameter.

If you’d like to use custom page fields in your section menus (e.g. translated field values, images, or other fields / methods) or if your page models override get_url_parts(), relative_url() or other Page methods involved in URL generation, you’ll likely want to update this.

To find out more about what values are supported and the effect they have, see: ‘Specific’ pages and menus

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 (See ‘Specific’ pages and menus). 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.