Back to Overview
daniel
Daniel Rotter

Core developer and support guru. Passionate traveler and soccer player.

danrot90
Back to Overview

How to use Sulu's navigation contexts

When we consult people during their first steps with Sulu a common question is how we deal with website navigations. We use a concept called "navigation contexts" and we covered this in our documentation. In this blog post I want to explain this a little more detailed.

The navigation is an essential part of the overall concept of a website. Most websites have more than one type of navigation. Often you'll find a main navigation on top of the site and another one in the footer. Sometimes web-designs require an additional sidebar navigation. The variations are almost endless.  

At the very beginning of the planning, the navigation contexts must be defined according to the web-design. The screenshot above shows the 2 navigations of the Sulu website. The menu on the right is the main navigation and the links in the footer are separated into two different lists. This means we have three navigation contexts:

  • main
  • footer_left
  • footer_right
Example of a website navigation

The following code shows the required part of the webspace configuration file:

<navigation>
    <contexts>
        <context key="main">
            <meta>
                <title lang="en">Mainnavigation</title>
            </meta>
        </context>
        <context key="footer_left">
            <meta>
                <title lang="en">Footernavigation Left</title>
            </meta>
        </context>
        <context key="footer_right">
            <meta>
                <title lang="en">Footernavigation Right</title>
            </meta>
        </context>
    </contexts>
</navigation>

After the template has been configured the content manager must assign the pages that should appear in the navigation to the navigation contexts. This is a big difference to other CMS as this is often done the other way round. In Sulu there is no separate menu for creating and assigning navigations. Here you use the dropdown in the “Settings” tab of each page to set the navigation contexts. 

In the following screenshot the link to the page will appear in the "main" and the "footer_left" navigation. The names in the dropdown are the titles of the meta tag in the webspace configuration.

Assigning navigation contexts to a page

The final step is to actually render the navigation with the assigned pages. Sulu offers some Twig extensions to make this process as easy as possible:

  • sulu_navigation_root_tree(context, depth, loadExcerpt)
  • sulu_navigation_root_flat(context, depth, loadExcerpt)
  • sulu_navigation_tree(uuid, context, depth, loadExcerpt, level)
  • sulu_navigation_flat(uuid, context, depth, loadExcerpt, level)

The methods containing root in their name return the navigation starting from the very first level, whereby the others only return pages being a descendant of the page with the given UUID. The context parameter is a filter based on the navigation context assigned to the page. The depth describes how many levels of pages the method should return, and loadExcerpt is a boolean deciding if the excerpt should additionally be loaded (default is false because of better performance).

So, probably the easiest way to show a simple navigation in a nested list looks like this:

<ul>
    {% for item in sulu_navigation_root_tree('main', 2) %}
    <li>
        <a href="{{ sulu_content_path(item.url) }}"
            title="{{ item.title }}">{{ item.title }}</a>
        {% if item.children|length > 0 %}
            <ul>
            {% for child in item.children %}
                <li><a href="{{ sulu_content_path(child.url) }}"
                        title="{{ child.title }}">
                    {{ child.title }}
                </a></li>
            {% endfor %}
            </ul>
        {% endif %}
    </li>
    {% endfor %}
</ul>
Rendering the navigation in Twig templates

Conclusion

Sulu’s concept of managing website navigations is a bit different from other content management systems. It gives more flexibility to the editor and is much easier to understand. Developers should avoid creating too many navigations contexts in the beginning since this is irritating and negatively affects the site performance. 

I hope that this explanation helps you to understand this concept! If you have questions please comment or join our #Slack channel.

daniel
Daniel Rotter

Core developer and support guru. Passionate traveler and soccer player.

danrot90