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 defaultuse_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
andWAGTAILMENUS_DEFAULT_FLAT_MENU_MAX_LEVELS
settings. Default values are now set using themax_levels
field on the menu objects themselves.Dropped support for the
WAGTAILMENUS_DEFAULT_MAIN_MENU_USE_SPECIFIC
andWAGTAILMENUS_DEFAULT_FLAT_MENU_USE_SPECFIC
settings. Default values are now set using theuse_specific
field on the menu objects themselves.The
has_submenu_items()
method onMenuPage
no longer accepts the check_for_children argument.The
modify_submenu_items()
andhas_submenu_items()
methods on theMenuPage
model now both accept an optionalmenu_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
(oruse_specific=0
)use_specific=USE_SPECIFIC_AUTO
(oruse_specific=1
)use_specific=USE_SPECIFIC_TOP_LEVEL
(oruse_specific=2
)use_specific=USE_SPECIFIC_ALWAYS
(oruse_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',
],
},
},
]