================================ Wagtailmenus 2.0.0 release notes ================================ .. contents:: :local: :depth: 1 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: .. code-block:: console 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: .. code-block:: python 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', ], }, }, ]