In this tutorial, you will learn how to leverage the Umbraco API in order to create a menu. One of the most common components on every website is the primary navigation menu. The menu allows your site visitors to be able to navigate around your site. There are many different ways of creating a menu in Umbraco, which technique is best all depends on your design. The most common menu is usually a simple one that mimics your page hierarchy in your CMS. In today's guide, I am going to cover the basics of creating a menu in Umbraco.
Children, Descendants, and DescendantsOrSelf
The basics of any websites menu are to display the child pages of the homepage. Umbraco provides us several useful API calls to do this, Children(), Descendants() and DescendantsOrSelf(). To describe what these different API calls do, I will use the hierarchy below to demonstrate.
-- News (level 1) -- World (level 2) -- Page 1 (level 3) -- Page 2 (level 3) -- About (level 1)
- Children() will only return the immediate children. In our example, this would be 'News' and 'About'
- Descendants() returns all of the children from the current page. In our example, this would return everything
- DescendantsOrSelf(int level) : This works the same as descendants, except you specify how far down the page hierarchy to go. It takes a parameter called level, a level that means the number of hierarchies down to stop looking for more ancestors. So, in our example, a level of 2 would return News, World and About
Get the current level
As I've mentioned in What is the Umbraco Helper? When we work with Razor and our Views it's best to use @Model to access the current page data as it provides us type safety, which means we can take advantage of the Razor syntax and IntelliSense will work. When we work with pages @Model.Content provides us access to the current page that we're on. So if we want to get the Children of the current page we would use this syntax
The last new concept we need to cover is the IsVisible property. When we work with content we might not want every single page to display on the menu. What happens if we had the T&C's page as a child of the homepage, we might not want to ignore that. Luckily, Umbraco provides a property on the default document type called IsVisible.
If you go to a page in your Umbraco tree, go to the 'Properties' tab and scroll to the bottom, you will see a property called 'Hide From Navigation'. When we are in our template, we can use the IsVisible() method to check if the content editor wants this page to be displayed in a menu.
A Simple Menu
I've now covered all the various calls to the API we need, so now it's time to write the actual menu code. For simplicity, I'm doing all this work in the template. To create a menu that displays all your top-level pages, you can use the following code:
When we add this add into the header in our sample site header now looks like the screenshot above. This menu is based on the content pages I created under the homepage, as seen below:
Creating A Menu With A Sub-Navigation
Now let's say we want to go one step further and have our menu display top level pages and also their subpages. We can equally do this, by using this snippet:
In the code above, I'm first getting a list of all level 1 descendants from the current page and rendering a link to it, using the pages Url and name property. For each page, check to see if it has any immediate children. If it does, render an ordered list and display with appropriate pages.
In this article, we've made our first Umbraco page a little bit more dynamic as well as covered some of the basics of the Umbraco API, specifically the difference between Children, Descendants and DescendantsOrSelf and how we can get different page sets based on the navigation structure. We've also gone over the benefits of using @model and how each page has an in-built 'Hide From Navigation' property that can be used to hide the pages the content editor has hidden in the backend.