================================
Wagtailmenus 2.4.0 release notes
================================

.. contents::
    :local:
    :depth: 2


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

Check out the new documentation!
--------------------------------

It's been a long wait, but I finally got around to making it happen. Wagtailmenus now has
easily navigable and searchable documentation, kindly hosted by ``readthedocs.org``. Find it at http://wagtailmenus.readthedocs.io/


New ``get_text_for_repeated_menu_item()`` method on ``MenuPageMixin`` and ``MenuPage`` models
---------------------------------------------------------------------------------------------

The new method is called by ``get_repeated_menu_item()`` to get a string to use to populate the ``text`` attribute on repeated menu items.

The method is designed to be overridden in cases where the text value needs to come from different fields. e.g. in multilingual site where different translations of 'repeated_item_text' must be surfaced.

By default, if the ``repeated_item_text`` field is left blank, the ``WAGTAILMENUS_PAGE_FIELD_FOR_MENU_ITEM_TEXT`` is respected, instead of
just returning ``Page.title``.


New ``use_absolute_page_urls`` parameter added to template tags
---------------------------------------------------------------

The new parameter allows you to render menus that use 'absolute' URLs
for pages (including the protocol/domain derived from the relevant 
``wagtail.core.models.Site`` object), instead of the 'relative' URLs used by
default.


Other minor changes
===================

*   Adjusted Meta classes on menu item models so that common behaviour is
    defined once in AbastractMenuItem.Meta.
*   Refactored the AbstractMenuItem's `menu_text` property method to improve
    code readability, and better handle instances where neither link_text or 
    link_page are set.


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

The signature of the ``modify_submenu_items()`` and ``get_repeated_menu_item()`` methods on ``MenuPage`` and ``MenuPageMixin`` models has been updated to accept a new ``use_absolute_page_urls`` keyword argument.

If you're overriding either of these methods in your project, you should think about updating the signatures of those methods to accept
the new argument and pass it through when calling ``super()``, like in the following example:

.. code-block:: python

    from wagtailmenus.models import MenuPage


    class ContactPage(MenuPage):
        ...

        def modify_submenu_items(
            self, menu_items, current_page, current_ancestor_ids, 
            current_site, allow_repeating_parents, apply_active_classes,
            original_menu_tag, menu_instance, request, use_absolute_page_urls,
        ):
            # Apply default modifications first of all
            menu_items = super(ContactPage, self).modify_submenu_items(
                menu_items, current_page, current_ancestor_ids, current_site, allow_repeating_parents, apply_active_classes, original_menu_tag,
                menu_instance, request, use_absolute_page_urls
            )
            """
            If rendering a 'main_menu', add some additional menu items to the end
            of the list that link to various anchored sections on the same page
            """
            if original_menu_tag == 'main_menu':
                base_url = self.relative_url(current_site)
                menu_items.extend((
                    {
                        'text': 'Get support',
                        'href': base_url + '#support',
                        'active_class': 'support',
                    },
                    {
                        'text': 'Speak to someone',
                        'href': base_url + '#call',
                        'active_class': 'call',
                    },
                    {
                        'text': 'Map & directions',
                        'href': base_url + '#map',
                        'active_class': 'map',
                    },
                ))
            return menu_items

        def get_repeated_menu_item(
            self, current_page, current_site, apply_active_classes,
            original_menu_tag, request, use_absolute_page_urls,
        ):
            item = super(ContactPage, self).get_repeated_menu_item(
                current_page, current_site, apply_active_classes,
                original_menu_tag, request, use_absolute_page_urls,
            )
            item.text = 'Eat. Sleep. Rave. Repeat!'
            return item


If you choose NOT to update your versions of those methods to accept the ``use_absolute_page_urls`` keyword argument, you will continue to see deprecation warnings until version ``2.6.0``, when it will be a requirement, and your existing code will no longer work.

You might want to consider adopting a more future-proof approach to overriding the methods from ``MenuPage`` and ``MenuPageMixin``, so that new keyword arguments added in future will be catered for automatically. 

Below shows a version of the above code example, modified to use ``**kwargs`` in methods:

.. code-block:: python

    from wagtailmenus.models import MenuPage


    class ContactPage(MenuPage):
        ...

        def modify_submenu_items(self, menu_items, **kwargs):
            # Apply default modifications first of all
            menu_items = super(ContactPage, self).modify_submenu_items(menu_items, **kwargs)
            """
            If rendering a 'main_menu', add some additional menu items to the end
            of the list that link to various anchored sections on the same page
            """
            if kwargs['original_menu_tag'] == 'main_menu':
                base_url = self.relative_url(kwargs['current_site'])
                menu_items.extend((
                    {
                        'text': 'Get support',
                        'href': base_url + '#support',
                        'active_class': 'support',
                    },
                    {
                        'text': 'Speak to someone',
                        'href': base_url + '#call',
                        'active_class': 'call',
                    },
                    {
                        'text': 'Map & directions',
                        'href': base_url + '#map',
                        'active_class': 'map',
                    },
                ))
            return menu_items

        def get_repeated_menu_item(self, current_page, **kwargs):
            item = super(ContactPage, self).get_repeated_menu_item(current_page, **kwargs)
            item.text = 'Eat. Sleep. Rave. Repeat!'
            return item