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
WAGTAILMENUS_FLATMENU_MENU_ICON
WAGTAILMENUS_FLAT_MENUS_HANDLE_CHOICES
WAGTAILMENUS_FLAT_MENUS_EDITABLE_IN_WAGTAILADMIN
WAGTAILMENUS_FLAT_MENUS_MODELADMIN_CLASS
WAGTAILMENUS_MAINMENU_MENU_ICON
WAGTAILMENUS_MAIN_MENUS_EDITABLE_IN_WAGTAILADMIN
WAGTAILMENUS_MAIN_MENUS_MODELADMIN_CLASS
- Default templates and template finder settings
- Default tag behaviour settings
WAGTAILMENUS_FLAT_MENUS_FALL_BACK_TO_DEFAULT_SITE_MENUS
WAGTAILMENUS_GUESS_TREE_POSITION_FROM_PATH
WAGTAILMENUS_DEFAULT_ADD_SUB_MENUS_INLINE
WAGTAILMENUS_DEFAULT_CHILDREN_MENU_MAX_LEVELS
WAGTAILMENUS_DEFAULT_SECTION_MENU_MAX_LEVELS
WAGTAILMENUS_DEFAULT_CHILDREN_MENU_USE_SPECIFIC
WAGTAILMENUS_DEFAULT_SECTION_MENU_USE_SPECIFIC
- Menu class and model override settings
- Miscellaneous 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:
# settings.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 editing ‘Flat menus’ in the Wagtail CMS.
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.
# settings.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 editing ‘Main menus’ in the Wagtail CMS.
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.
# settings.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:
# settings.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.
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
Menu class and model override settings¶
WAGTAILMENUS_CHILDREN_MENU_CLASS
¶
Default value: 'wagtailmenus.models.menus.ChildrenMenu'
Use this to specify a custom menu class to be used by wagtailmenus’ children_menu
tag. The value should be the import path of your custom class as a string, e.g. 'mysite.appname.models.CustomClass'
.
For more details see: Overriding the menu class used by {% children_menu %}
WAGTAILMENUS_FLAT_MENU_MODEL
¶
Default value: 'wagtailmenus.FlatMenu'
Use this to specify a custom model to use for flat menus instead of the default. The model should be a subclass of wagtailmenus.AbstractFlatMenu
.
For more details see: Overriding the models used for flat menus
WAGTAILMENUS_FLAT_MENU_ITEMS_RELATED_NAME
¶
Default value: 'menu_items'
Use this to specify the ‘related name’ that should be used to access menu items from flat menu instances. Used to replace the default FlatMenuItem model with a custom one.
For more details see: Overriding the models used for flat menus
WAGTAILMENUS_MAIN_MENU_MODEL
¶
Default value: 'wagtailmenus.MainMenu'
Use this to specify an alternative model to use for main menus. The model should be a subclass of wagtailmenus.AbstractMainMenu
.
For more details see: Overriding the models used for main menus
WAGTAILMENUS_MAIN_MENU_ITEMS_RELATED_NAME
¶
Default value: 'menu_items'
Use this to specify the ‘related name’ that should be used to access menu items from main menu instances. Used to replace the default MainMenuItem
model with a custom one.
For more details see: Overriding the models used for main menus
WAGTAILMENUS_SECTION_MENU_CLASS
¶
Default value: 'wagtailmenus.models.menus.SectionMenu'
Use this to specify a custom class to be used by wagtailmenus’ section_menu
tag. The value should be the import path of your custom class as a string, e.g. 'mysite.appname.models.CustomClass'
.
For more details see: Overriding the menu class used by {% section_menu %}
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.