5. Navigation

There are four template tags for use in the templates that are connected to the menu:

• show_menu
• show_menu_below_id
• show_sub_menu
• show_breadcrumb

Note

Please note that menus were originally implemented to be application-independant and as such, live in the menus application instead of the “normal” cms

5.1. show_menu

{% show_menu %} renders the navigation of the current page. You can overwrite the appearance and the HTML if you add a menu/menu.html template to your project or edit the one provided with django-cms. show_menu takes four optional parameters: start_level, end_level, extra_inactive, and extra_active.

The first two parameters, start_level (default=0) and end_level (default=100) specify from what level to which level should the navigation be rendered. If you have a home as a root node and don’t want to display home you can render the navigation only after level 1.

The third parameter, extra_inactive (default=0), specifies how many levels of navigation should be displayed if a node is not a direct ancestor or descendant of the current active node.

Finally, the fourth parameter, extra_active (default=100), specifies how many levels of descendants of the currently active node should be displayed.

5.1.1. Some Examples

Complete navigation (as a nested list):

{% load cache menu_tags %}
<ul>
    {% show_menu 0 100 100 100 %}
</ul>

Navigation with active tree (as a nested list):

<ul>
    {% show_menu 0 100 0 100 %}
</ul>

Navigation with only one active extra level:

<ul>
    {% show_menu 0 100 0 1 %}
</ul>

Level 1 navigation (as a nested list):

<ul>
    {% show_menu 1 %}
</ul>

Navigation with a custom template:

{% show_menu 0 100 100 100 "myapp/menu.html" %}

5.2. show_menu_below_id

If you have set an id in the advanced settings of a page, you can display the submenu of this page with a template tag. For example, we have a page called meta that is not displayed in the navigation and that has the id “meta”:

<ul>
    {% show_menu_below_id "meta" %}
</ul>

You can give it the same optional parameters as show_menu:

<ul>
    {% show_menu_below_id "meta" 0 100 100 100 "myapp/menu.html" %}
</ul>

5.3. show_sub_menu

Display the sub menu of the current page (as a nested list). Takes one argument that specifies how many levels deep should the submenu be displayed. The template can be found at menu/sub_menu.html:

<ul>
    {% show_sub_menu 1 %}
</ul>

Or with a custom template:

<ul>
    {% show_sub_menu 1 "myapp/submenu.html" %}
</ul>

5.4. show_breadcrumb

Show the breadcrumb navigation of the current page. The template for the HTML can be found at menu/breadcrumb.html.:

{% show_breadcrumb %}

Or with a custom template and only display level 2 or higher:

{% show_breadcrumb 2 "myapp/breadcrumb.html" %}

If the current URL is not handled by the CMS or you are working in a navigation extender, you may need to provide your own breadcrumb via the template. This is mostly needed for pages like login, logout and third-party apps.

5.5. Properties of Navigation Nodes in templates

{{ node.is_leaf_node }}

Is it the last in the tree? If true it doesn’t have any children. (This normally comes from mptt.)

{{ node.level }}

The level of the node. Starts at 0.

{{ node.menu_level }}

The level of the node from the root node of the menu. Starts at 0. If your menu starts at level 1 or you have a “soft root” (described in the next section) the first node still would have 0 as its menu_level.

{{ node.get_absolute_url }}

The absolute URL of the node.

{{ node.get_title }}

The title in the current language of the node.

{{ node.selected }}

If true this node is the current one selected/active at this URL.

{{ node.ancestor }}

If true this node is an ancestor of the current selected node.

{{ node.sibling }}

If true this node is a sibling of the current selected node.

{{ node.descendant }}

If true this node is a descendant of the current selected node.

{{ node.soft_root }}

If true this node is a “soft root”.

5.6. Soft Roots

“Soft roots” are pages that start a new navigation. If you are in a child of a soft root node you can only see the path to the soft root. This feature is useful if you have big navigation trees with a lot of pages and don’t want to overwhelm the user.

To enable it put the following in your settings.py file:

CMS_SOFTROOT = True

Now you can mark a page as “soft root” in the ‘Advanced’ tab of the page’s settings in the admin interface.

5.7. Modifying & Extending the menu

Please refer to the App Integration documentation