Wagtailmenus 2.0.0 release notes

What’s new?

New use_specific and max_levels fields for menu models

MainMenu and FlatMenu models now have two new fields:

  • use_specific: To allow the default use_specific setting when rendering that menu to be changed via the Wagtail CMS.

  • max_levels: To allow the default max_levels setting when rendering that menu to be changed via the admin area.

Find the field in the collapsed ADVANCED SETTINGS panel at the bottom of the edit form

More use_specific options available

The use_specific menu tag argument can now be one of 4 integer values, allowing for more fine-grained control over the use of Page.specific and PageQuerySet.specific() when rendering menu tags.

Developers not using the MenuPage model or overriding any of wagtail’s Page` methods involved in URL generation can now enjoy better performance by choosing not to fetch any specific pages at all during rendering. Simply pass ``use_specific=USE_SPECIFIC_OFF or use_specific=0 to the tag, or update the use_specific field value on your MainMenu or FlatMenu objects via the Wagtail admin area.

Basic argument validation added to template tags

The max_levels, use_specific, parent_page and menuitem_or_page arguments passed to all template tags are now checked to ensure their values are valid, and if not, raise a ValueError with a helpful message to aid debugging.

Upgrade considerations

Dropped features

  • Dropped support for the WAGTAILMENUS_DEFAULT_MAIN_MENU_MAX_LEVELS and WAGTAILMENUS_DEFAULT_FLAT_MENU_MAX_LEVELS settings. Default values are now set using the max_levels field on the menu objects themselves.

  • Dropped support for the WAGTAILMENUS_DEFAULT_MAIN_MENU_USE_SPECIFIC and WAGTAILMENUS_DEFAULT_FLAT_MENU_USE_SPECFIC settings. Default values are now set using the use_specific field on the menu objects themselves.

  • The has_submenu_items() method on MenuPage no longer accepts the check_for_children argument.

  • The modify_submenu_items() and has_submenu_items() methods on the MenuPage model now both accept an optional menu_instance keyword argument.

  • Added the WAGTAILMENUS_ADD_EDITOR_OVERRIDE_STYLES setting to allow override styles to be disabled.

Run migrations after updating!

New fields have been added to MainMenu and FlatMenu models, so you’ll need to run the migrations for those. Run the following:

django manage.py migrate wagtailmenus

Setting max_levels and use_specific on your existing menus

Edit your existing MainMenu and FlatMenu objects via the Wagtail CMS.

You should see a new collapsed ADVANCED SETTINGS panel at the bottom of each form, where both of these fields live.

Default values for MainMenu are max_levels=2 and use_specific=1.

Default values for FlatMenu are max_levels=1 and use_specific=1.

Switch to using the new use_specific options

If you’re passing use_specific=True or use_specific=False to the any of the menu tags, you’ll need to change that to one of the following:

  • use_specific=USE_SPECIFIC_OFF (or use_specific=0)

  • use_specific=USE_SPECIFIC_AUTO (or use_specific=1)

  • use_specific=USE_SPECIFIC_TOP_LEVEL (or use_specific=2)

  • use_specific=USE_SPECIFIC_ALWAYS (or use_specific=3)

See the following section of the README for further info: https://github.com/jazzband/wagtailmenus/blob/v2.0.0/README.md#using-menupage

Changes to MenuPage.has_submenu_items() and MenuPage.modify_submenu_items()

If you’re extending these methods on your custom page types, you will likely need to make a few changes.

Firstly, the check_for_children argument is no longer supplied to has_submenu_items(), and is will no longer be accepted as a value.

Secondly, both the modify_submenu_items() and has_submenu_items() methods both accept an optional menu_instance argument, which you’ll need to also accept.

See the updated section of the README for corrected code examples: https://github.com/jazzband/wagtailmenus/blob/v2.0.0/README.md#11-manipulating-sub-menu-items-for-specific-page-types

Adding the context_processor to settings

If you’re upgrading from wagtailmenus version 1.5.1 or lower, you’ll need to update your settings to include a context_processor from wagtailmenus. Your TEMPLATES setting should look something like the example below:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            os.path.join(PROJECT_ROOT, 'templates'),
        ],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.contrib.auth.context_processors.auth',
                'django.template.context_processors.debug',
                'django.template.context_processors.i18n',
                'django.template.context_processors.media',
                'django.template.context_processors.request',
                'django.template.context_processors.static',
                'django.template.context_processors.tz',
                'django.contrib.messages.context_processors.messages',
                'wagtail.contrib.settings.context_processors.settings',
                'wagtailmenus.context_processors.wagtailmenus',
            ],
        },
    },
]