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 instances use_specific attribute value is correctly passed to hooks.
• Removed request, max_levels and use_specific as class attributes from Menu 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