From 6395822f8204b8ee34c07956b101e6489ee5c4d5 Mon Sep 17 00:00:00 2001 From: Andy Babic Date: Thu, 18 Jun 2020 12:57:32 +0100 Subject: [PATCH] Minor documentation improvements (#370) Authored-by: Andy Babic --- docs/source/advanced_topics/hooks.rst | 28 ++- docs/source/installation.rst | 13 +- docs/source/overview.rst | 195 +++++++++++++++--- docs/source/releases/3.0.2.rst | 2 +- .../rendering_menus/custom_templates.rst | 112 +++++----- .../template_tag_reference.rst | 89 ++++++-- docs/source/settings_reference.rst | 4 +- 7 files changed, 324 insertions(+), 119 deletions(-) diff --git a/docs/source/advanced_topics/hooks.rst b/docs/source/advanced_topics/hooks.rst index b5628978e..d69203c07 100644 --- a/docs/source/advanced_topics/hooks.rst +++ b/docs/source/advanced_topics/hooks.rst @@ -54,7 +54,7 @@ By default, ``get_base_page_queryset()`` applies a few simple filters to prevent Page.objects.filter(live=True, expired=False, show_in_menus=True) -However, if you'd like to filter this result down further, you can do so using something like the following: +However, if you'd like to filter this result down further, you can do so using something like the following: .. NOTE:: @@ -137,7 +137,7 @@ However, if you'd only like to include a subset of the CMS-defined menu item, or NOTE: MUST ALWAYS RETURN A QUERYSET """ if( - current_site.hostname.startswith('intranet.') and + current_site.hostname.startswith('intranet.') and request.user.is_authenticated() ): queryset = queryset.exclude(handle__contains="visiting-only") @@ -163,9 +163,9 @@ These changes would be applied to all menu types that use menu items to define t NOTE: MUST ALWAYS RETURN A QUERYSET """ if( - original_menu_tag == 'flat_menu' and + original_menu_tag == 'flat_menu' and menu_instance.handle == 'action-links' and - current_site.hostname.startswith('intranet.') and + current_site.hostname.startswith('intranet.') and request.user.is_authenticated() ): queryset = queryset.exclude(handle__contains="visiting-only") @@ -245,7 +245,7 @@ This hook allows you to modify the list of items **after** they have been 'prime link to the RKH website NOTE: This result won't undergo any more processing before sending to - a template for rendering, so you may need to set 'href' and + a template for rendering, so you may need to set 'href' and 'text' attributes / keys so that those values are picked up by menu templates. """ @@ -294,7 +294,7 @@ Below is a full list of the additional arguments that are passed to methods usin An integer value indicating the 'level' or 'depth' that is currently being rendered in the process of rendering a multi-level menu. This will start at `1` for the first/top-level items of a menu, and increment by `1` for each additional level. ``max_levels`` - An integer value indicating the maximum number of levels that should be rendered for the current menu. This will either have been specified by the developer using the ``max_levels`` argument of a menu tag, or might have been set in the CMS for a specific ``MainMenu`` or ``FlatMenu`` instance. + An integer value indicating the maximum number of levels that should be rendered for the current menu. This will either have been specified by the developer using the ``max_levels`` argument of a menu tag, or might have been set in the CMS for a specific ``MainMenu`` or ``FlatMenu`` instance. ``current_site`` A Wagtail ``Site`` instance, indicating the site that the current request is for (usually also available as ``request.site``) @@ -312,13 +312,13 @@ Below is a full list of the additional arguments that are passed to methods usin ├── About us ├── What we do ├── Careers - | ├── Vacancy one - | └── Vacancy two + │ ├── Vacancy one + │ └── Vacancy two ├── News & events - | ├── News - | | ├── Article one - | | └── Article two - | └── Events + │ ├── News + │ │ ├── Article one + │ │ └── Article two + │ └── Events └── Contact us If the current page was 'Vacancy one', the section root page would be 'Careers'. Or, if the current page was 'Article one', the section root page would be 'News & events'. @@ -327,9 +327,7 @@ Below is a full list of the additional arguments that are passed to methods usin A boolean value indicating the preferred policy for having pages that subclass ``MenuPageMixin`` add a repeated versions of themselves to it's children pages (when rendering a `sub_menu` for that page). For more information see: :ref:`menupage_and_menupagemixin`. ``apply_active_classes`` - A boolean value indicating the preferred policy for setting ``active_class`` attributes on menu items for the current menu. + A boolean value indicating the preferred policy for setting ``active_class`` attributes on menu items for the current menu. ``use_absolute_page_urls`` A boolean value indicating the preferred policy for using full/absolute page URLs for menu items representing pages (observed by ``prime_menu_items()`` when setting the ``href`` attribute on each menu item). In most cases this will be ``False``, as the default behaviour is to use 'relative' URLs for pages. - - diff --git a/docs/source/installation.rst b/docs/source/installation.rst index d48d6fcc7..b7e10b07d 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -14,6 +14,7 @@ Installing wagtailmenus ``INSTALLED_APPS`` setting in your project settings: .. code-block:: python + :caption: settings.py INSTALLED_APPS = [ ... @@ -26,6 +27,8 @@ Installing wagtailmenus should look something like this: .. code-block:: python + :caption: settings.py + :emphasize-lines: 19 TEMPLATES = [ { @@ -75,11 +78,11 @@ Installing wagtailmenus ├── About us ├── What we do ├── Careers - | ├── Vacancy one - | └── Vacancy two + │ ├── Vacancy one + │ └── Vacancy two ├── News & events - | ├── News - | └── Events + │ ├── News + │ └── Events └── Contact us Running the command from the console: @@ -112,7 +115,7 @@ Installing wagtailmenus * News & events * Contact us - .. NOTE :: + .. note :: The 'autopopulate_main_menus' command is meant as 'run once' command to help you get started, and will only affect menus that do not already have any menu items defined. Running it more than once won't have any diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 300573bb0..991012312 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -13,64 +13,201 @@ Overview and key concepts Better control over top-level menu items ======================================== -When you have a 'main navigation' menu powered purely by the page tree, things can get a little tricky, as the main menu is often designed in a way that is very sensitive to change. Some moderators might not understand that publishing a new page at the top level (or reordering those pages) will dramatically affect the main navigation (and possibly even break the design). And really, *why should they?* +When you have a 'main navigation' menu powered purely by the page tree, things can get a +little tricky, as the main menu is often designed in a way that is very sensitive to +change. Some moderators might not understand that publishing a new page at the top level +(or reordering those pages) will dramatically affect the main navigation (and possibly +even break the design). And really, *why should they?* -Wagtailmenus solves this problem by allowing you to choose exactly which pages should appear as top-level items. It adds new functionality to Wagtail's CMS, allowing you to simply and effectively create and manage menus, using a familiar interface. +Wagtailmenus solves this problem by allowing you to choose exactly which pages should +appear as top-level items. It adds new functionality to Wagtail's CMS, allowing you to +simply and effectively create and manage menus, using a familiar interface. -You can also use Wagtail's built-in group permissions system to control which users have permission to make changes to menus. +You can also use Wagtail's built-in group permissions system to control which users +have permission to make changes to menus. Link to pages, custom URLs, or a combination of both ==================================================== -The custom URL field won't force you to enter a valid URL, so you can add things like ``#request-callback`` or ``#signup`` to link to areas on the active page (perhaps as JS modals). +The custom URL field will not force you to enter a valid URL, so you can add things like +``#request-callback`` or ``#signup`` to link to areas on the active page (perhaps as JS +modals). -You can also define additional values to be added to a page's URL, letting you jump to a specific anchor point on a page, or include fixed GET parameters for analytics or to trigger custom functionality. +You can also define additional values to be added to a page's URL, letting you jump to a +specific anchor point on a page, or include fixed GET parameters for analytics or to +trigger custom functionality. -Multi-level menus generated from your existing page tree -======================================================== - -We firmly believe that your page tree is the best place to define the structure, and the 'natural order' of pages within your site. Wagtailmenus only allows you to define the top-level items for each menu, because offering anything more would inevitably lead to site managers redefining parts of the page tree in multiple places, doomed to become outdated as the original tree changes over time. - -To generate multi-level menus, wagtailmenus takes the top-level items you define for each menu and automatically combines it with your page tree, efficiently identifying descendants for each selected page and outputting them as sub-menus following the page tree's structure and order. +Multi-level menus generated from your page tree +=============================================== -You can prevent any page from appearing in menus by simply setting ``show_in_menus`` to ``False``. Pages will also no longer be included in menus if they are unpublished. +We firmly believe that your page tree is the best place to define the structure and +'natural order' (the ordering applied to all ``PageQuerySet`` results by default) of +pages within your site. Wagtailmenus deliberately only allows you to choose the top-level +items for each menu, because offering anything more would inevitably lead to editors +redefining parts of the page tree in multiple places, doomed to become outdated as the +original tree changes over time. When you move or reorder pages, do you really want to +have to stop and think "Where else do I need to change this?". + +To generate multi-level menus, wagtailmenus takes the top-level items you selected and +dynamically generates the rest from your page tree, using the same structure and order. + +.. note:: + In the CMS, Wagtail tends to list pages in order of when they were last updated. + You can list pages in their 'natural order' (and reorder them) by following + `these instructions from the Wagtail documentation `_. + + +Multi-level menu examples +------------------------- + +Imagine your page tree had the following structure: + +.. code-block:: none + + Home + ├── What we do + │ ├── Aiding and supporting + │ ├── Researching + │ └── Driving change + ├── Latest news + │ ├── Article one (``show_in_menus=False``) + │ ├── Article two (``show_in_menus=False``) + │ └── Article three (``show_in_menus=False``) + ├── Find an outlet + │ ├── Bristol + │ │ └── City Centre outlet (``show_in_menus=False``) + │ ├── Leicestershire + │ │ ├── Hinckley outlet (``show_in_menus=False``) + │ │ └── Leicester outlet (``show_in_menus=False``) + │ ├── London + │ │ ├── Camden outlet (``show_in_menus=False``) + │ │ └── Peckham outlet (``show_in_menus=False``) + │ └── Oxfordshire (``live=False``) + │ └── Oxford outlet (``show_in_menus=False``) + ├── Get involved + │ ├── Local community groups + │ ├── Schools and young people + │ ├── Help as a company + │ └── Donate + ├── Careers + │ ├── Vacancy one (``show_in_menus=False``) + │ └── Vacancy two (``show_in_menus=False``) + ├── Policies + │ ├── Terms and conditions + │ ├── Cookie policy + │ └── Privacy policy + └── Contact us + +And for your menu, you selected the following pages as menu items: + +- What we do (``allow_subnav=True``) +- Get involved (``allow_subnav=True``) +- Latest news (``allow_subnav=True``) +- Donate (``allow_subnav=True``) + +This would generate a menu with the following structure (with ``max_levels=2``): + +.. code-block:: none + + ├── What we do + │ ├── Aiding and supporting + │ ├── Researching + │ └── Driving change + ├── Get involved + │ ├── Local community groups + │ ├── Schools and young people + │ ├── Help as a company + │ └── Donate + ├── Latest news + └── Donate + +.. note:: + Have you noticed how the aricle pages are not shown below the 'Latest news' item, + despite specifying ``allow_subnav=True`` on the menu item? Only pages with a + ``show_in_menus`` value of ``True`` will be displayed (at any level) in rendered + menus. The field is added by Wagtail, so is present for all custom page types. + + For page types that are better suited to showing on listing/index pages (for example: + news articles or events) - you can set the ``show_in_menus_default`` attribute on + the page type class to ``False`` to exclude them from menus by default. + +You could also define another menu with the following pages selected as items: + +- Careers (``allow_subnav=True``) +- Policies (``allow_subnav=False``) +- Find an outlet (``allow_subnav=True``) + +This would generate a menu with the following structure (with ``max_levels=2``): + +.. code-block:: none + + ├── Careers + ├── Policies + └── Find an outlet + ├── Bristol + ├── Leicestershire + └── London + +.. note:: + Have you noticed how 'Oxfordshire' is not shown alongside the other counties below + 'Find an outlet'? Only live/published pages will be displayed (at any level) in + rendered menus. You can still select unpublished pages as items (in case you want + to update your menu ahead of publishing), but wagtailmenus will automatically + exclude unpublished pages at the time of rendering. Define menus for all your project needs ======================================= -Have you ever hard-coded a menu into a footer at the start of a project, only for those pages never to come into existence? Or maybe the pages were created, but their URLs changed later on, breaking the hard-coded links? How about 'secondary navigation' menus in headers? +Have you ever hard-coded a menu into a footer at the start of a project, only for those +pages never to come into existence? Or maybe the pages were created, but their URLs +changed later on, breaking the hard-coded links? How about 'secondary navigation' menus +in headers? -As well as giving you control over your 'main menu', wagtailmenus allows you to manage any number of additional menus via the CMS as 'flat menus', meaning they too can benefit from page links that dynamically update to reflect tree position or status changes. +As well as giving you control over your 'main menu', wagtailmenus allows you to manage +any number of additional menus via the CMS as 'flat menus', meaning they too can benefit +from page links that dynamically update to reflect tree position or status changes. -Don't hard-code another menu again! CMS-managed menus allow you to make those 'emergency changes' and 'last-minute tweaks' without having to touch a single line of code. +Don't hard-code another menu again! CMS-managed menus allow you to make those 'emergency +changes' and 'last-minute tweaks' without having to touch a single line of code. -.. NOTE:: - Despite the name, 'flat menus' can be configured to render as multi-level menus if you need them to. +.. note:: + Despite the name, 'flat menus' can be configured to render as multi-level menus if + you need them to. Suitable for single-site or multi-site projects =============================================== -While main menus always have to be defined for each site, for flat menus, you can support multiple sites using any of the following approaches: +While main menus always have to be defined for each site, for flat menus, you can support +multiple sites using any of the following approaches: * Define a new menu for each site * Define a menu for your default site and reuse it for the others -* Create new menus for some sites, but use the default site's menu for others +* Create new menus for some sites, but use the default site's menu for others -You can even use different approaches for different flat menus in the same project. If you'd like to learn more, take a look at the ``fall_back_to_default_site_menus`` option in :ref:`flat_menu_args` +You can even use different approaches for different flat menus in the same project. If +you'd like to learn more, take a look at the ``fall_back_to_default_site_menus`` option +in :ref:`flat_menu_args` -A **copy** feature is also available from the flat menu management interface, allowing you to quickly and easily copy existing menus from one site to another. +A **copy** feature is also available from the flat menu management interface, allowing +you to quickly and easily copy existing menus from one site to another. -In a multi-site project, you can also configure wagtailmenus to use separate sets of templates for each site for rendering (See :ref:`custom_templates_auto`) +In a multi-site project, you can also configure wagtailmenus to use separate sets of +templates for each site for rendering (See :ref:`custom_templates_auto`) Solves the problem of important page links becoming just 'toggles' in multi-level menus ======================================================================================= -Extend the ``wagtailmenus.models.MenuPage`` model instead of the usual ``wagtail.wagtailcore.models.Page`` model to create your custom page types, and gain a couple of extra fields that will allow you to configure certain pages to appear again alongside their children in multi-level menus. Use the menu tags provided, and that behaviour will remain consistent in all menus throughout your site. To find out more, see: :ref:`menupage_and_menupagemixin` +Extend the ``wagtailmenus.models.MenuPage`` model instead of the usual +``wagtail.wagtailcore.models.Page`` model to create your custom page types, and gain a +couple of extra fields that will allow you to configure certain pages to appear again +alongside their children in multi-level menus. Use the menu tags provided, and that +behaviour will remain consistent in all menus throughout your site. To find out more, +see: :ref:`menupage_and_menupagemixin` .. image:: _static/images/repeating-item.png :alt: Screenshot showing the repeated nav item in effect @@ -79,8 +216,12 @@ Extend the ``wagtailmenus.models.MenuPage`` model instead of the usual ``wagtail Use the default menu templates for rendering, or easily add your own ==================================================================== -Each menu tag comes with a default template that's designed to be fully accessible and compatible with Bootstrap 3. However, if you don't want to use the default templates, wagtailmenus makes it easy to use your own, using whichever approach works best for you: +Each menu tag comes with a default template that's designed to be fully accessible and +compatible with Bootstrap 3. However, if you don't want to use the default templates, +wagtailmenus makes it easy to use your own, using whichever approach works best for you: -- Use settings to change the default templates used for each tag -- Specify templates using ``template`` and ``sub_menu_template`` arguments for any of the included menu tags (See :ref:`custom_templates_specify`). -- Put your templates in a preferred location within your project and wagtailmenus will pick them up automatically (See :ref:`custom_templates_auto`). +- Use settings to change the default templates used for each tag +- Specify templates using ``template`` and ``sub_menu_template`` arguments for any of the + included menu tags (See :ref:`custom_templates_specify`). +- Put your templates in a preferred location within your project and wagtailmenus will + pick them up automatically (See :ref:`custom_templates_auto`). diff --git a/docs/source/releases/3.0.2.rst b/docs/source/releases/3.0.2.rst index df9c04f31..d0c442a87 100644 --- a/docs/source/releases/3.0.2.rst +++ b/docs/source/releases/3.0.2.rst @@ -7,7 +7,7 @@ Minor changes * Added support for Wagtail 2.9 (no code changes necessary) (Sekani Tembo). * Added compatibility with Django Sites Framework [1]_ (Sekani Tembo). -* Minor documentation updates (Sekani Tembo). +* Minor documentation updates. .. rubric:: Footnotes .. [1] Be sure to update code according to Wagtail 2.9 Release \ *Notes'* diff --git a/docs/source/rendering_menus/custom_templates.rst b/docs/source/rendering_menus/custom_templates.rst index 553bed0e0..155a8f639 100644 --- a/docs/source/rendering_menus/custom_templates.rst +++ b/docs/source/rendering_menus/custom_templates.rst @@ -11,7 +11,7 @@ Using your own menu templates ----- Writing custom menu templates -============================= +============================= .. _template_context_variables: @@ -20,7 +20,7 @@ What context variables are available to use? The following variables are added to the context for each menu template or sub-menu template that you create: -:``menu_items``: +:``menu_items``: If the template is for rendering the first level of a main or flat menu, then ``menu_items`` will be a list of ``MainMenuItem`` or ``FlatMenuItem`` objects (respectively). In all other cases. it will be a list ``Page`` @@ -30,54 +30,54 @@ The following variables are added to the context for each menu template or sub-m item to help keep you menu templates consistent. For more information see: :ref:`menu_items_added_attributes` -:``current_level``: +:``current_level``: An integer indicating the current level being rendered. This starts at - ``1`` for the initial template tag call, then increments by one for each - additional ``
    `` level that is added by calling the ``{% sub_menu %}`` + ``1`` for the initial template tag call, then increments by one for each + additional ``
      `` level that is added by calling the ``{% sub_menu %}`` tag -:``max_levels``: +:``max_levels``: An integer indicating the maximum number of levels that should be rendered for the current menu, as determined by the original ``main_menu``, ``section_menu``, ``flat_menu`` or ``children_menu`` tag call. -:``current_template``: - The name of the template currently being used for rendering. This is most - useful when rendering a ``sub_menu`` template that calls ``sub_menu`` +:``current_template``: + The name of the template currently being used for rendering. This is most + useful when rendering a ``sub_menu`` template that calls ``sub_menu`` recursively, and you wish to use the same template for all recursions. -:``sub_menu_template``: - The name of the template that should be used for rendering any further +:``sub_menu_template``: + The name of the template that should be used for rendering any further levels (should be picked up automatically by the ``sub_menu`` tag). -:``original_menu_tag``: +:``original_menu_tag``: A string value indicating the name of the tag that was originally called in order to - render the branch currently being rendered. The value will be one of + render the branch currently being rendered. The value will be one of ``"main_menu"``, ``"flat_menu"``, ``"section_menu"``, ``"children_menu"`` or ``"sub_menu"``. -:``allow_repeating_parents``: +:``allow_repeating_parents``: A boolean indicating whether ``MenuPage`` fields should be respected when rendering further menu levels. -:``apply_active_classes``: - A boolean indicating whether ``sub_menu`` +:``apply_active_classes``: + A boolean indicating whether ``sub_menu`` tags should attempt to add 'active' and 'ancestor' classes to menu items when rendering further menu levels. -:``use_absolute_page_urls``: +:``use_absolute_page_urls``: A boolean indicating whether absolute page URLs should be used for page links when rendering. .. _menu_items_added_attributes: -Attributes added to each item in ``menu_items`` +Attributes added to each item in ``menu_items`` ----------------------------------------------- -Whether ``menu_items`` is a list of ``Page``, ``MainMenuItem`` or ``FlatMenuItem`` objects, the following additional attributes are added to each item to help improve consistency of menu templates: +Whether ``menu_items`` is a list of ``Page``, ``MainMenuItem`` or ``FlatMenuItem`` objects, the following additional attributes are added to each item to help improve consistency of menu templates: -:``href``: +:``href``: The URL that the menu item should link to. :``text``: @@ -87,16 +87,16 @@ Whether ``menu_items`` is a list of ``Page``, ``MainMenuItem`` or ``FlatMenuItem attribute by utilising the :ref:`DEFAULT_PAGE_FIELD_FOR_MENU_ITEM_TEXT` setting. -:``active_class``: +:``active_class``: A class name to indicate the 'active' state of the menu item. The value will be 'active' if linking to the current page, or 'ancestor' if linking to one of it's ancestors. - You can change the CSS class strings used to indicate 'active' and + You can change the CSS class strings used to indicate 'active' and 'ancestor' statuses by utilising the :ref:`ACTIVE_CLASS` and :ref:`ACTIVE_ANCESTOR_CLASS` settings. -:``has_children_in_menu``: +:``has_children_in_menu``: A boolean indicating whether the menu item has children that should be output as a sub-menu. @@ -108,7 +108,7 @@ Getting wagtailmenus to use your custom menu templates .. _custom_templates_auto: -Using preferred paths and names for your templates +Using preferred paths and names for your templates -------------------------------------------------- This is the easiest (and recommended) approach for getting wagtailmenus to use your custom menu templates for rendering. @@ -165,7 +165,7 @@ For a multi-level main menu that displays three levels of links, your templates .. _custom_templates_flat_menu: -Preferred template paths for ``{% flat_menu %}`` +Preferred template paths for ``{% flat_menu %}`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For flat menus, the tag also uses the `handle` field of the specific menu being rendered, so that you can have wagtailmenus use different templates for different menus. @@ -234,7 +234,7 @@ Or, if the ``info`` menu only ever needed to show one level of menu items, you m templates └── menus - └── info.html + └── info.html If your were happy for most of your flat menus to share the same templates, you might put those common templates in the same folder where they'd automatically get selected for all flat menus: @@ -254,14 +254,14 @@ Building on the above example, you could then override menu templates for certai templates └── menus └── flat - ├── level_1.html - ├── level_2.html - ├── level_3.html + ├── level_1.html + ├── level_2.html + ├── level_3.html ├── info - | | # This location is preferred when rendering an 'info' menu - | └── level_2.html # Only override the level 2 template + │ │ # This location is preferred when rendering an 'info' menu + │ └── level_2.html # Only override the level 2 template └── contact - | # This location is preferred when rendering a 'contact' menu + │ # This location is preferred when rendering a 'contact' menu └── level_1.html # Only override the level 1 template @@ -283,16 +283,16 @@ The above structure would work, but it's not ideal. Imagine if a new front-end d templates └── menus └── flat - | # Still used by default (e.g. for menus with different handles) - ├── level_1.html - ├── level_2.html - ├── level_3.html + │ # Still used by default (e.g. for menus with different handles) + ├── level_1.html + ├── level_2.html + ├── level_3.html ├── info - | | # This location is preferred when rendering an 'info' menu - | ├── level_1.html # {% extends 'menus/flat/level_1.html' %} - | └── level_2.html # Our custom template from before + │ │ # This location is preferred when rendering an 'info' menu + │ ├── level_1.html # {% extends 'menus/flat/level_1.html' %} + │ └── level_2.html # Our custom template from before └── contact - | # This location is preferred when rendering a 'contact' menu + │ # This location is preferred when rendering a 'contact' menu ├── level_1.html # Our custom template from before └── level_2.html # {% extends 'menus/flat/level_2.html' %} @@ -303,16 +303,16 @@ That's better, but you might even like to make the ``info`` and ``contact`` temp templates └── menus ├── flat - | | # Still used by default (e.g. for menus with different handles) - | ├── level_1.html - | ├── level_2.html - | └── level_3.html + │ │ # Still used by default (e.g. for menus with different handles) + │ ├── level_1.html + │ ├── level_2.html + │ └── level_3.html ├── info - | | # This location is still preferred when rendering an 'info' menu - | ├── level_1.html # {% includes 'menus/flat/level_1.html' %} - | └── level_2.html # Our custom template from before + │ │ # This location is still preferred when rendering an 'info' menu + │ ├── level_1.html # {% includes 'menus/flat/level_1.html' %} + │ └── level_2.html # Our custom template from before └── contact - | # This location is still preferred when rendering a 'contact' menu + │ # This location is still preferred when rendering a 'contact' menu ├── level_1.html # Our custom template from before └── level_2.html # {% includes 'menus/flat/level_2.html' %} @@ -322,7 +322,7 @@ The templates in the ``info`` and ``contact`` folders will still be preferred ov .. _custom_templates_section_menu: -Preferred template paths for ``{% section_menu %}`` +Preferred template paths for ``{% section_menu %}`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. NOTE:: @@ -371,7 +371,7 @@ Or, if your section menu only needs to surface the first of level of pages withi .. _custom_templates_children_menu: -Preferred template paths for ``{% children_menu %}`` +Preferred template paths for ``{% children_menu %}`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. NOTE:: @@ -406,7 +406,7 @@ If your project needs multi-level children menus, displaying two levels of links └── menus └── children ├── level_1.html # Used by the {% children_menu %} tag for the 1st level - └── level_2.html # Used by the {% sub_menu %} tag for the 2nd level + └── level_2.html # Used by the {% sub_menu %} tag for the 2nd level Or, if you only need single-level children menus, you might structure things more simply, like so: @@ -430,7 +430,7 @@ Even if the various menus in your project tend to share a lot of common template Specifying menu templates using template tag parameters ------------------------------------------------------- -All template tags included in wagtailmenus support ``template``, ``sub_menu_template`` and ``sub_menu_templates`` arguments to allow you to explicitly override the templates used during rendering. +All template tags included in wagtailmenus support ``template``, ``sub_menu_template`` and ``sub_menu_templates`` arguments to allow you to explicitly override the templates used during rendering. For example, if you had created the following templates in your project's root 'templates' directory: @@ -442,12 +442,16 @@ You could make :ref:`main_menu` use those templates for rendering by specifying .. code-block:: html + {% load menu_tags %} + {% main_menu max_levels=3 template="custom_menus/main_menu.html" sub_menu_templates="custom_menus/main_menu_sub.html, custom_menus/main_menu_sub_level_2.html" %} Or, if you only wanted to use a single template for sub menus, you could specify that template like so: .. code-block:: html - + + {% load menu_tags %} + {# A 'sub_menu_templates' value without commas is recognised as a single template #} {% main_menu max_levels=3 template="custom_menus/main_menu.html" sub_menu_templates="custom_menus/main_menu_sub.html" %} @@ -458,6 +462,8 @@ Or you could just override one or the other, like so: .. code-block:: html + {% load menu_tags %} + {# Just override the top-level template #} {% main_menu max_levels=3 template="custom_menus/main_menu.html" %} diff --git a/docs/source/rendering_menus/template_tag_reference.rst b/docs/source/rendering_menus/template_tag_reference.rst index dc5b17397..5797fe75b 100644 --- a/docs/source/rendering_menus/template_tag_reference.rst +++ b/docs/source/rendering_menus/template_tag_reference.rst @@ -102,8 +102,8 @@ No ``bool`` ``False`` By default, relative page URLs are used for the ``href`` attribute on page links when rendering your menu. If you wish to use absolute page URLs instead, add ``use_absolute_page_urls=True`` to the ``main_menu`` tag in your template. The preference will also be respected automatically by any subsequent calls to ``{% sub_menu %}`` during the course of rendering the menu (unless explicitly overridden in custom menu templates ). - .. NOTE: - Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. +.. NOTE: + Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. ----- @@ -124,7 +124,11 @@ By default, you have to call the ``{% sub_menu %}`` tag within a menu template t For example, instead of the following: .. code-block:: html + :caption: templates/menus/main_menu.html + {% load menu_tags %} + +
        {% for item in menu_items %}
      • {{ item.text }} @@ -133,19 +137,27 @@ For example, instead of the following: {% endif %}
        • {% endfor %} +
      You could do: .. code-block:: html + :caption: templates/menus/main_menu.html +
        {% for item in menu_items %}
      • {{ item.text }} - {% if item.has_children_in_menu %} - {{ item.sub_menu.render_to_template }} + {% if item.sub_menu %} + {% endif %}
        • {% endfor %} +
      .. TIP: 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. @@ -199,6 +211,8 @@ Allows you to specify multiple templates to use for rendering different levels o .. code-block:: html + {% load menu_tags %} + {% main_menu max_levels=3 template="level_1.html" sub_menu_templates="level_2.html, level_3.html" %} If not provided, wagtailmenus will attempt to find suitable sub menu templates automatically. @@ -348,7 +362,11 @@ By default, you have to call the ``{% sub_menu %}`` tag within a menu template t For example, instead of the following: .. code-block:: html + :caption: templates/menus/flat_menu.html + {% load menu_tags %} + +
        {% for item in menu_items %}
      • {{ item.text }} @@ -357,19 +375,27 @@ For example, instead of the following: {% endif %}
        • {% endfor %} +
      You could do: .. code-block:: html + :caption: templates/menus/flat_menu.html +
        {% for item in menu_items %}
      • {{ item.text }} - {% if item.has_children_in_menu %} - {{ item.sub_menu.render_to_template }} + {% if item.sub_menu %} + {% endif %}
        • {% endfor %} +
      .. TIP: 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. @@ -404,8 +430,8 @@ No ``bool`` ``False`` By default, relative page URLs are used for the ``href`` attribute on page links when rendering your menu. If you wish to use absolute page URLs instead, add ``use_absolute_page_urls=True`` to the ``{% flat_menu %}`` tag in your template. The preference will also be respected automatically by any subsequent calls to ``{% sub_menu %}`` during the course of rendering the menu (unless explicitly overridden in custom menu templates). - .. NOTE: - Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. +.. NOTE: + Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. ----- @@ -439,6 +465,8 @@ Allows you to specify multiple templates to use for rendering different levels o .. code-block:: html + {% load menu_tags %} + {% flat_menu 'info' template="level_1.html" sub_menu_templates="level_2.html, level_3.html" %} If not provided, wagtailmenus will attempt to find suitable sub menu templates automatically. @@ -557,8 +585,8 @@ No ``bool`` ``False`` By default, relative page URLs are used for the ``href`` attribute on page links when rendering your menu. If you wish to use absolute page URLs instead, add ``use_absolute_page_urls=True`` to the ``{% section_menu %}`` tag in your template. The preference will also be respected automatically by any subsequent calls to ``{% sub_menu %}`` during the course of rendering the menu (unless explicitly overridden in custom menu templates). - .. NOTE: - Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. +.. NOTE: + Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. ----- @@ -578,7 +606,11 @@ By default, you have to call the ``{% sub_menu %}`` tag within a menu template t For example, instead of the following: .. code-block:: html + :caption: templates/menus/section_menu.html + {% load menu_tags %} + +
        {% for item in menu_items %}
      • {{ item.text }} @@ -587,19 +619,27 @@ For example, instead of the following: {% endif %}
        • {% endfor %} +
      You could do: .. code-block:: html + :caption: templates/menus/section_menu.html +
        {% for item in menu_items %}
      • {{ item.text }} - {% if item.has_children_in_menu %} - {{ item.sub_menu.render_to_template }} + {% if item.sub_menu %} + {% endif %}
        • {% endfor %} +
      .. TIP: 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. @@ -653,6 +693,8 @@ Allows you to specify multiple templates to use for rendering different levels o .. code-block:: html + {% load menu_tags %} + {% section_menu max_levels=3 template="level_1.html" sub_menu_templates="level_2.html, level_3.html" %} If not provided, wagtailmenus will attempt to find suitable sub menu templates automatically. @@ -757,8 +799,8 @@ No ``bool`` ``False`` By default, relative page URLs are used for the ``href`` attribute on page links when rendering your menu. If you wish to use absolute page URLs instead, add ``use_absolute_page_urls=True`` to the ``{% children_menu %}`` tag in your template. The preference will also be respected automatically by any subsequent calls to ``{% sub_menu %}`` during the course of rendering the menu (unless explicitly overridden in custom menu templates). - .. NOTE: - Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. +.. NOTE: + Using absolute URLs will have a negative impact on performance, especially if you're using a Wagtail version prior to 1.11. ----- @@ -778,7 +820,11 @@ By default, you have to call the ``{% sub_menu %}`` tag within a menu template t For example, instead of the following: .. code-block:: html + :caption: templates/menus/children_menu.html + {% load menu_tags %} + +
        {% for item in menu_items %}
      • {{ item.text }} @@ -787,19 +833,27 @@ For example, instead of the following: {% endif %}
        • {% endfor %} +
      You could do: .. code-block:: html + :caption: templates/menus/children_menu.html +
        {% for item in menu_items %}
      • {{ item.text }} - {% if item.has_children_in_menu %} - {{ item.sub_menu.render_to_template }} + {% if item.sub_menu %} + {% endif %}
        • {% endfor %} +
      .. TIP: 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. @@ -853,6 +907,8 @@ Allows you to specify multiple templates to use for rendering different levels o .. code-block:: html + {% load menu_tags %} + {% children_menu max_levels=3 template="level_1.html" sub_menu_templates="level_2.html, level_3.html" %} If not provided, wagtailmenus will attempt to find suitable sub menu templates automatically. @@ -875,6 +931,7 @@ Example usage ------------- .. code-block:: html + :caption: templates/menus/sub_menu.html {% load menu_tags %} diff --git a/docs/source/settings_reference.rst b/docs/source/settings_reference.rst index 49fd081b0..6e55f5243 100644 --- a/docs/source/settings_reference.rst +++ b/docs/source/settings_reference.rst @@ -66,7 +66,7 @@ For example, if your project uses an 'info' menu in the header, a 'footer' menu Default value: ``True`` -By default, 'Flat menus' are editable in the Wagtail CMS. Setting this to `False` in your project's settings will disable editing 'Flat menus' in the Wagtail CMS. +By default, 'Flat menus' are editable in the Wagtail CMS. Setting this to ``False`` in your project's settings will disable this functionality, and remove the **Flat menus** item from Wagtail's **Settings** menu. .. _FLAT_MENUS_MODELADMIN_CLASS: @@ -105,7 +105,7 @@ Use this to change the icon used to represent 'Main menus' in the Wagtail CMS. Default value: ``True`` -By default, 'Main menus' are editable in the Wagtail CMS. Setting this to `False` in your project's settings will disable editing 'Main menus' in the Wagtail CMS. +By default, 'Main menus' are editable in the Wagtail CMS. Setting this to ``False`` in your project's settings will disable this functionality, and remove the **Main menus** item from Wagtail's **Settings** menu. .. _MAIN_MENUS_MODELADMIN_CLASS: