Releases: jazzband/wagtailmenus
v2.1.0
NOTE: There is a know bug with this release when attempting to install using pip. Please update to v2.1.1 instead.
New / updated features
- Added official support for wagtail v1.8
- Added
WAGTAILMENUS_MAIN_MENU_MODEL
andWAGTAILMENUS_FLAT_MENU_MODEL
settings to allow the default main and flat menu models to be swapped out for
custom models. - Added
WAGTAILMENUS_MAIN_MENU_ITEMS_RELATED_NAME
and
WAGTAILMENUS_FLAT_MENU_ITEMS_RELATED_NAME
settings to allow the default
menu item models to be swapped out for custom models. - Added the
WAGTAILMENUS_PAGE_FIELD_FOR_MENU_ITEM_TEXT
setting to allow
developers to specify a page attribute other thantitle
to be used to
populate thetext
attribute for menu items linking to pages. - Added german translation by Pierre (@bloodywing).
Under the hood
- Split models.py into 3 logically-named files to make models easier to find.
- Turned
wagtailmenus.app_settings
into a real settings module.
Upgrade considerations
N/A
v2.0.3
v2.0.2
v2.0.1
v2.0.0
New / updated features
- The
use_specific
menu tag argument can now be one of 4 integer values, allowing for more fine-grained control over the use ofPage.specific
andPageQuerySet.specific()
when rendering menu tags. MainMenu
andFlatMenu
models now have ause_specific
field, to allow the defaultuse_specific
setting when rendering that menu to be changed via the Wagtail admin area. Find the field in the collapsed ADVANCED SETTINGS panel at the bottom of the edit formMainMenu
andFlatMenu
models now have amax_levels
field, to allow the defaultmax_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- Developers not using the
MenuPage
class or overriding any of wagtailPage
methods involved in URL generation can now enjoy better performance by choosing not to fetch any specific pages at all during rendering. Simply passuse_specific=USE_SPECIFIC_OFF
oruse_specific=0
to the tag, or update theuse_specific
field value on yourMainMenu
orFlatMenu
instances via the Wagtail admin area. - 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
max_levels
,use_specific
,parent_page
andmenuitem_or_page
arguments passed to all template tags are now checked to ensure their values are valid, and if not, raise aValueError
with a helpful message to aid debugging. - The
has_submenu_items()
method onMenuPage
no longer accepts thecheck_for_children
argument. - The
modify_submenu_items()
andhas_submenu_items()
methods on theMenuPage
model now both accept an optionalmenu_instance
value, so that menu_instance might be called to access pre-fetched page data without hitting the database. - Added the
WAGTAILMENUS_ADD_EDITOR_OVERRIDE_STYLES
setting to allow override styles to be disabled.
Under the hood
- When rendering a multi-level
MainMenu
orFlatMenu
, those models now pre-fetch all of pages needed for menu generation and allow menu tags to request the desired pages from them as they are needed, reducing the need to hit the database multiple times. If you need to use specific pages in main or flat menus, you should see a significant improvement in performance. - Eliminated a lot of code duplication in template tags by adding the
get_sub_menu_items_for_page
method, which is used bysub_menu
,section_menu
andchildren_menu
to do most of their work. - The default
show_multiple_levels
value for theflat_menu
tag is nowTrue
instead ofFalse
. The defaultmax_levels
field value forFlatMenu
instances is1
, which has the same effect. Only, the value can be changed via the admin area, and the changes will reflected immediately without having to explicitly addshow_multiple_levels=True
to the tag in templates. - Other minor performance improvements.
Upgrade considerations
1. Run migrations
New fields have been added to MainMenu
and FlatMenu
models, so you'll need to run the migrations for those. Run the following from your console:
django manage.py migrate wagtailmenus
2. Set max_levels
and use_specific
on your existing menus
Edit your existing MainMenu
and FlatMenu
instances via the Wagtail admin area. There's 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=AUTO
.
Default values for FlatMenu
are max_levels=1
and use_specific=AUTO
.
3. Understanding changes to use_specific
template tag 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/rkhleics/wagtailmenus/blob/v2.0.0/README.md#using-menupage
4. 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 not 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 factor in.
See the updated section of the README for corrected code examples:
https://github.com/rkhleics/wagtailmenus/blob/v2.0.0/README.md#11-manipulating-sub-menu-items-for-specific-page-types
5. 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',
],
},
},
]
v1.6.1
v1.6.0
What's changed?
- Improved confirmation messages when saving a menu in the admin area.
- Added a new test to submit the
MainMenu
edit form and check that
it behaves as expected. - Added some styles to menu add/edit/copy views to improve the UI.
- Added a new
context_processor
to handle some of the logic that was
previously being done in template tags. Django'sSimpleLazyObject
class is
used to reduce the overhead as much as possible, only doing the work when the
values are accessed by menu tags. - Added the
WAGTAILMENUS_GUESS_TREE_POSITION_FROM_PATH
setting to allow
developers to disable the 'guess tree position from path' functionality
that comes into play when serving custom views, where thebefore_serve_page
hook isn't activated, andwagtailmenu_params_helper()
inwagtail_hooks.py
doesn't get to add it's helpful values to the request/context. - Updated tox environment settings to run tests against wagtail==1.7, and
updated pinned wagtail version insetup.py
to reflect compatibility. - Added unicode support for python 2.7 and added missing verbose_names to
fields so that they can be translated (Alexey Krasnov & Andy Babic). - Added support for a
WAGTAILMENUS_FLAT_MENUS_HANDLE_CHOICES
setting that, if
set, will turn theCharField
used for FlatMenu.handle in add/edit/copy
forms into aChoiceField
, with that setting as the available choices.
Upgrade Considerations
Adding the context_processor
to settings
Wagtailmenus now requires a context_processor
to be active in order for menu tags to work. If upgrading to version 1.6.0
, you'll need to update the TEMPLATES
setting to include the new context_processor, like so:
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',
],
},
},
]
v1.5.1
What's changed?
MenuPage.has_submenu_items()
is now only ever called ifcheck_for_children
is True inmenu_tags.prime_menu_items()
. This way, themax_levels
value supplied to the original menu tag is always respected, with no additional levels ever being rendered. Thecheck_for_children
value passed tohas_submenu_items()
is now always True. Since removing would add breaking changes, it will be removed in a later feature release.- Fixed a migration-related issue that was causing Django to create new migrations for the app in some environments (Thanks to @nadersoliman for raising/helping).
- Fixed an issue where not all help text was marked for translation (Thanks to @nadersoliman for raising/helping).
v1.5.0
What's changed?
- Updated FlatMenu listing in CMS to only show site column and filters if menus are defined for more than one site.
- Added the
fall_back_to_default_site_menus
option to theflat_menu
tag, to allow flat menus defined for the default site to be used as fall-backs, in cases where the 'current' site doesn't have its own menus set up with the specified handle. - Added a custom ValidationError to FlatMenu's
clean()
method that better handles theunique_together
rule applied tosite
andhandle
fields. - Added the ability to copy/duplicate existing FlatMenu objects between sites (or to the same site with a different handle) via Wagtail's admin area. The 'Copy' button appears in the listing for anyone with 'add' permission, and the view allows the user to make changes before anything is saved.
- Apply
active
classes to menu items that link to custom URLs (ifrequest.path
andlink_url
are exact matches). - Added a
handle
toMenuItem
model to provide a string which can be used to do specific matching of menu items in the template. (Tim Leguijt)
Upgrade considerations:
- You'll need to run
django manage.py migrate wagtailmenus
after pulling down this latest version, in order to add the new 'handle' field for MainMenuItem and FlatMenuItem models.