===============================
Wagtailmenus 2.12 release notes
===============================

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


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


New ``add_sub_menus_inline`` option for menu tags
-------------------------------------------------

By default, you have to call the ``{% sub_menu %}`` tag within a menu template to render new branches of a multi-level menu. However, if you add ``add_sub_menus_inline=True`` to the initial ``{% main_menu %}``, ``{% flat_menu %}``, ``{% children_menu %}`` or ``{% section_menu %}`` tag, then sub menu instances will be created added directly to any menu item where ``item.has_children_in_menu`` is ``True``, allowing you to easily render the entire menu structure from within the same template.

For example, instead of the following:

.. code-block:: html

    {% for item in menu_items %}
        <li class="{{ item.active_class }}">
            <a href="{{ item.href }}">{{ item.text }}</a>
            {% if item.has_children_in_menu %}
                {% sub_menu item %}
            {% endif %}
        </li>       
    {% endfor %}
 
You could do:
 
.. code-block:: html
 
     {% for item in menu_items %}
        <li class="{{ item.active_class }}">
            <a href="{{ item.href }}">{{ item.text }}</a>
            {% if item.has_children_in_menu %}
                {{ item.sub_menu.render_to_template }}
            {% endif %}
        </li>       
    {% endfor %}
    
If you'd rather have sub menus be added inline by default (without having to add ``add_sub_menus_inline=True`` each time you use a template tag), you can change the default behaviour for all template tags by overriding the :ref:`DEFAULT_ADD_SUB_MENUS_INLINE` setting in your project's Django settings.

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

- Arabic translations added - Courtesy of @alfuhigi. Many thanks!
- Fixed an issue with the section menu in the release notes section of the docs.
- Changed the signature of ``Menu.render_from_tag()`` to better indicate common expected/supported arguments for menus.
- Fixed ``Menu.get_common_hook_kwargs()``, so the menu instances ``use_specific`` attribute value is correctly passed to hooks.
- Removed ``request``, ``max_levels`` and ``use_specific`` as class attributes from ``Menu`` to prevent unexpected mutation.
- Added a custom ``render_from_tag()`` method for each individual menu class, with a signature that highlights all relevant options, including those specific to that menu type.
- Renamed ``Menu.get_contextual_vals_from_context()`` to ``_create_contextualvals_obj_from_context()``.
- Renamed ``Menu.get_option_vals_from_options`` to ``_create_optionvals_obj_from_values()``.


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

The following items have been deprecated in this release. They will continue to be supported for a standard deprecation period of two minor releases, but will be removed in version 3.0.


``Menu.get_instance_for_rendering()``
-------------------------------------

In an effort to make method names more reflective of their functionality, this method has been replaced by two methods:
``create_from_collected_values()`` and ``get_from_collected_values()``. The former is implemented on menu classes that are  not model based (where instances must be created from scratch each time, for example: ``ChildrenMenu``, ``SectionMenu``, ``SubMenu``), and the latter is implemented on model-based menu classes, where a corresponding object must be retrieved from the database (so, ``AbstractMainMenu``, ``MainMenu``, ``AbstractFlatMenu`` and ``FlatMenu``). 

``render_from_tag()`` automatically calls one or the other, depending on whether the class inherits from ``django.db.models.Model``.

If you're using custom menu classes in your project, and are currently overriding ``get_instance_for_rendering()`` for any of those classes, you should update your code to override one of the new methods instead. Both of these new methods accept the same arguments, and return the same values, so the transition should be very easy.


``Menu.get_contextual_vals_from_context()``
-------------------------------------------

In an effort to make method names more reflective of their functionality, and to help dissuade users from overriding functionality that is subject to change, this method has been renamed to ``_create_contextualvals_obj_from_context()`` (becoming a private method in the process).


``Menu.get_option_vals_from_options()``
---------------------------------------

In an effort to make method names more reflective of their functionality, and to help dissuade users from overriding functionality that is subject to change, this method has been renamed to ``_create_optionvals_obj_from_values()`` (becoming a private method in the process).


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

Following a standard deprecation period a two minor releases, the following functionality has now been removed.


The WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH setting is no longer supported
------------------------------------------------------------------------

If you're using this to override the menu class used to render children menus in your project, you'll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_CHILDREN_MENU_CLASS.

For example, if you had the following:

.. code-block:: python

    # settings/base.py

    WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH = 'project.menus.CustomChildrenMenu'

You would change this to:

.. code-block:: python

    WAGTAILMENUS_CHILDREN_MENU_CLASS = 'project.menus.CustomChildrenMenu'


The WAGTAILMENUS_SECTION_MENU_CLASS_PATH setting is no longer supported
-----------------------------------------------------------------------

If you're using this to override the menu class used to render section menus in your project, you'll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_SECTION_MENU_CLASS.

For example, if you had the following:

.. code-block:: python

    # settings/base.py

    WAGTAILMENUS_SECTION_MENU_CLASS_PATH = 'project.menus.CustomSectionMenu'

You would change this to:

.. code-block:: python

    WAGTAILMENUS_SECTION_MENU_CLASS = 'project.app.module.CustomSectionMenu'


The ``wagtailmenus.app_settings`` module has been removed
---------------------------------------------------------

If you're importing this in your project from it's previous location, you should update the import statements in your code to use the new module path: ``wagtailmenus.conf.settings``

For example, instead of the following:

.. code-block:: python

    from wagtailmenus import app_settings

You should do:

.. code-block:: python

    from wagtailmenus.conf import settings


The ``wagtailmenus.constants`` module has been removed
------------------------------------------------------

If you're importing this in your project from it's previous location, you should update the import statements in your code to use the new module path: ``wagtailmenus.conf.constants``

For example, instead of the following:

.. code-block:: python

    from wagtailmenus import constants

You should do:

.. code-block:: python

    from wagtailmenus.conf import constants