==============================
Wagtailmenus 2.8 release notes
==============================

.. contents::
    :local:
    :depth: 1


What's new?
===========

Smarter 'active class' attribution for menu items that link to custom URLs 
--------------------------------------------------------------------------

By default, menu items linking to custom URLs are currently only attributed with the 'active' class if their ``link_url`` value matches the path of the current request **exactly**, producing unexpected results when GET parameters or fragments are added to the end of a ``link_url`` value.

A new and improved approach to active class attribution for custom URL links has now been implemented (by Joshua C. Jackson and Andy Babic), which you can enable by adding ``WAGTAILMENUS_CUSTOM_URL_SMART_ACTIVE_CLASSES = True`` to your project's settings.

With the new approach, only the 'path' part of the ``link_url`` value is used for comparison with ``request.path``, which produces far more consistent results. The new approach also allows the 'ancestor' class to be attributed to menu items where the ``link_url`` looks like an ancestor of the current request URL. For example, if a menu item's ``link_url`` value is ``'/news/'``, and the request path is ``'/news/boring-news-article/'``, then the menu item will be attributed with the 'ancestor' class.

The previous behaviour is now deprecated in favour of this new approach, and will be removed in version 2.10, with the new approach becoming the default (and only) option.


Minor changes & bug fixes 
=========================

- Various documentation spelling/formatting corrections (thanks to Sergey Fedoseev and Pierre Manceaux).


Deprecations
============

- The current 'active class' attribution behaviour for menu items linking to custom URLs is deprecated (see above for details). Add ``WAGTAILMENUS_CUSTOM_URL_SMART_ACTIVE_CLASSES = True`` to your project's settings to enable the new and improved behaviour and silence the deprecation warning.


Upgrade considerations
======================

Following the standard deprecation period, the following classes, methods and
behaviour have been removed:

-   Wagtailmenus now unconditionally uses backend-specific templates for rendering, and the ``WAGTAILMENUS_USE_BACKEND_SPECIFIC_TEMPLATES`` setting is ignored completely. See the 2.6 release notes for more info: http://wagtailmenus.readthedocs.io/en/stable/releases/2.6.0.html#improved-compatibility-with-alternative-template-backends. 
-   The ``get_template_engine()`` method has been removed from ``wagtailmenus.models.menus.Menu``.
-   The ``panels`` attribute has been removed from the ``AbstractMainMenu`` and ``AbstractFlatMenu`` models, as have the ``main_menu_panels`` and ``flat_menu_panels`` panel definition values from ``wagtailmenus.panels``.