v2.4.0

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 navigatable 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 overriden 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 param 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 wagtailcore.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 overrding 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:

    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:

    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