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 ``