Wagtailmenus 2.12 release notes¶
What’s new?¶
New add_sub_menus_inline
option for menu tags¶
By default, you have to call the {% sub_menu %}
tag within a menu template to render new branches of a multi-level menu. However, if you add add_sub_menus_inline=True
to the initial {% main_menu %}
, {% flat_menu %}
, {% children_menu %}
or {% section_menu %}
tag, then sub menu instances will be created added directly to any menu item where item.has_children_in_menu
is True
, allowing you to easily render the entire menu structure from within the same template.
For example, instead of the following:
{% for item in menu_items %}
<li class="{{ item.active_class }}">
<a href="{{ item.href }}">{{ item.text }}</a>
{% if item.has_children_in_menu %}
{% sub_menu item %}
{% endif %}
</li>
{% endfor %}
You could do:
{% for item in menu_items %}
<li class="{{ item.active_class }}">
<a href="{{ item.href }}">{{ item.text }}</a>
{% if item.has_children_in_menu %}
{{ item.sub_menu.render_to_template }}
{% endif %}
</li>
{% endfor %}
If you’d rather have sub menus be added inline by default (without having to add add_sub_menus_inline=True
each time you use a template tag), you can change the default behaviour for all template tags by overriding the WAGTAILMENUS_DEFAULT_ADD_SUB_MENUS_INLINE setting in your project’s Django settings.
Minor changes & bug fixes¶
Arabic translations added - Courtesy of @alfuhigi. Many thanks!
Fixed an issue with the section menu in the release notes section of the docs.
Changed the signature of
Menu.render_from_tag()
to better indicate common expected/supported arguments for menus.Fixed
Menu.get_common_hook_kwargs()
, so the menu instancesuse_specific
attribute value is correctly passed to hooks.Removed
request
,max_levels
anduse_specific
as class attributes fromMenu
to prevent unexpected mutation.Added a custom
render_from_tag()
method for each individual menu class, with a signature that highlights all relevant options, including those specific to that menu type.Renamed
Menu.get_contextual_vals_from_context()
to_create_contextualvals_obj_from_context()
.Renamed
Menu.get_option_vals_from_options
to_create_optionvals_obj_from_values()
.
Deprecations¶
The following items have been deprecated in this release. They will continue to be supported for a standard deprecation period of two minor releases, but will be removed in version 3.0.
Menu.get_instance_for_rendering()
¶
In an effort to make method names more reflective of their functionality, this method has been replaced by two methods:
create_from_collected_values()
and get_from_collected_values()
. The former is implemented on menu classes that are not model based (where instances must be created from scratch each time, for example: ChildrenMenu
, SectionMenu
, SubMenu
), and the latter is implemented on model-based menu classes, where a corresponding object must be retrieved from the database (so, AbstractMainMenu
, MainMenu
, AbstractFlatMenu
and FlatMenu
).
render_from_tag()
automatically calls one or the other, depending on whether the class inherits from django.db.models.Model
.
If you’re using custom menu classes in your project, and are currently overriding get_instance_for_rendering()
for any of those classes, you should update your code to override one of the new methods instead. Both of these new methods accept the same arguments, and return the same values, so the transition should be very easy.
Menu.get_contextual_vals_from_context()
¶
In an effort to make method names more reflective of their functionality, and to help dissuade users from overriding functionality that is subject to change, this method has been renamed to _create_contextualvals_obj_from_context()
(becoming a private method in the process).
Menu.get_option_vals_from_options()
¶
In an effort to make method names more reflective of their functionality, and to help dissuade users from overriding functionality that is subject to change, this method has been renamed to _create_optionvals_obj_from_values()
(becoming a private method in the process).
Upgrade considerations¶
Following a standard deprecation period a two minor releases, the following functionality has now been removed.
The WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH setting is no longer supported¶
If you’re using this to override the menu class used to render children menus in your project, you’ll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_CHILDREN_MENU_CLASS.
For example, if you had the following:
# settings/base.py
WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH = 'project.menus.CustomChildrenMenu'
You would change this to:
WAGTAILMENUS_CHILDREN_MENU_CLASS = 'project.menus.CustomChildrenMenu'
The WAGTAILMENUS_SECTION_MENU_CLASS_PATH setting is no longer supported¶
If you’re using this to override the menu class used to render section menus in your project, you’ll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_SECTION_MENU_CLASS.
For example, if you had the following:
# settings/base.py
WAGTAILMENUS_SECTION_MENU_CLASS_PATH = 'project.menus.CustomSectionMenu'
You would change this to:
WAGTAILMENUS_SECTION_MENU_CLASS = 'project.app.module.CustomSectionMenu'
The wagtailmenus.app_settings
module has been removed¶
If you’re importing this in your project from it’s previous location, you should update the import statements in your code to use the new module path: wagtailmenus.conf.settings
For example, instead of the following:
from wagtailmenus import app_settings
You should do:
from wagtailmenus.conf import settings
The wagtailmenus.constants
module has been removed¶
If you’re importing this in your project from it’s previous location, you should update the import statements in your code to use the new module path: wagtailmenus.conf.constants
For example, instead of the following:
from wagtailmenus import constants
You should do:
from wagtailmenus.conf import constants