Skip navigation

Manage navigation

Tomas Nosek
5 min read
Download PDF

Whether displayed as a website menu or navigation in your mobile app, navigation builds a hierarchy in your project. In Kontent.ai, your content creators can manage navigation menus without developer assistance if you model your navigation.

Table of contents

    Key points

    Suitable navigation approach

    Navigation is composed of content items based on a content type dedicated for navigation. Define the relationships in the navigation using a subpages element if you use Web Spotlight or with linked items element in other cases.

    When modeling the navigation, decide whether to bind content to the navigation or keep them separate.

    Navigation bound to content

    This way, items that you link in the subpages or linked items element also hold the content. While this approach is more straightforward for understanding the concept, it isn't suitable for omnichannel delivery.

    That's why it's more suitable for smaller projects or projects that use one way of navigation for all channels.

    Navigation separate from content

    If you separate navigation from content, you're creating two items for content linked from your navigation. The first is for the content itself; the second is for a navigation item that links the first one.

    Separate navigation where pages in the page tree link to the actual content.

    This way is better for larger projects prepared for omnichannel content.

    Build your navigation

    Using Web Spotlight?

    If your project comes with Web Spotlight, some steps are already done for you. Check out our article on what's created automatically after Web Spotlight is activated.

    1. Create a content type for navigation items

    Create a new content type and add elements needed for your channel. For the code examples below, this tutorial calls this type Navigation item. It typically contains:

    • A text element for the title of the navigation item (Title in the code sample)
    • A subpages or linked items element for child menu items (Subitems)
    • A linked items element for the content itself
    • A URL slug element if you're building website navigation (URL)

    2. Define your root

    You need to define where your navigation begins. While websites typically have a homepage, other structures may have a root or main screen. You can use the content type created for navigation for the root navigation item or create a different content type for this purpose.

    Websites usually benefit from having a separate content type for their homepage. That's because homepages have a unique appearance and contain a different layout and content than on other pages.

    The code example below uses the navigation item for the homepage, created with the name Root navigation item.

    3. Create your navigation items

    Create content items using the created navigation content type and link them with the subpages or linked item element.

    Articles navigation item with two articles and a child item with two more articles in it.

    When finished, publish the root together with all its linked items.

    4. Retrieve your navigation items

    Developers now need to request the items via the Delivery API to generate your menu.

    Specify the depth parameter to retrieve more than one level of subpages or linked items if you want to show all navigation with one API call.

    • Java
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>");

// Registers the model class for navigation items
// Tip: Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
client.registerType(NavigationItem.class);

// Gets navigation items and their linked items
CompletionStage<NavigationItem> root = client.getItem(
    "root_navigation_item",
     NavigationItem.class,
     DeliveryParameterBuilder.params()
        .linkedItemsDepth(5)
        .build()

// Registers the model class for articles
client.registerType(Article.class);

// Gets specific elements of all articles
CompletionStage<List<Article>> articles = client.getItems(
    Article.class, 
    DeliveryParameterBuilder.params()
        .projection("title", "url")
        .build()
);
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>");

// Registers the model class for navigation items
// Tip: Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
client.registerType(NavigationItem.class);

// Gets navigation items and their linked items
CompletionStage<NavigationItem> root = client.getItem(
    "root_navigation_item",
     NavigationItem.class,
     DeliveryParameterBuilder.params()
        .linkedItemsDepth(5)
        .build()

// Registers the model class for articles
client.registerType(Article.class);

// Gets specific elements of all articles
CompletionStage<List<Article>> articles = client.getItems(
    Article.class, 
    DeliveryParameterBuilder.params()
        .projection("title", "url")
        .build()
);
    • JavaScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

// Gets navigation items and their linked items
const rootResponse = await deliveryClient.item('root_navigation_item')
  .depthParameter(5)
  .toPromise();

// Gets specific elements of all articles
const articleResponse = await deliveryClient.items()
  .type('article')
  .elementsParameter(['title', 'url'])
  .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

// Gets navigation items and their linked items
const rootResponse = await deliveryClient.item('root_navigation_item')
  .depthParameter(5)
  .toPromise();

// Gets specific elements of all articles
const articleResponse = await deliveryClient.items()
  .type('article')
  .elementsParameter(['title', 'url'])
  .toPromise();
    • C#
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;

// Tip: Use DI for this in your apps https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
      .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7")
      .Build();

// Gets navigation items and their linked items
// Tip: Create strongly typed models according to https://kontent.ai/learn/net-strong-types
IDeliveryItemResponse<NavigationItem> rootResponse = await client.GetItemAsync<NavigationItem>("root_navigation_item",
    new DepthParameter(5)
    );

NavigationItem root = rootResponse.Item;

// Gets specific elements of all articles
IDeliveryItemListingResponse<Article> articleResponse = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article"),
    new ElementsParameter("title", "url")
    );

var articles = articleResponse.Items;
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;

// Tip: Use DI for this in your apps https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
      .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7")
      .Build();

// Gets navigation items and their linked items
// Tip: Create strongly typed models according to https://kontent.ai/learn/net-strong-types
IDeliveryItemResponse<NavigationItem> rootResponse = await client.GetItemAsync<NavigationItem>("root_navigation_item",
    new DepthParameter(5)
    );

NavigationItem root = rootResponse.Item;

// Gets specific elements of all articles
IDeliveryItemListingResponse<Article> articleResponse = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article"),
    new ElementsParameter("title", "url")
    );

var articles = articleResponse.Items;
    • PHP
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php
// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use Kontent\Ai\Delivery\DeliveryClient;

$client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7');

// Gets navigation items and their linked items
$root = $client->getItem('root_navigation_item', (new QueryParams())
            ->depth(5));

// Gets specific elements of all articles
$articles = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')
            ->elements(array("title", "url")));
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php
// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use Kontent\Ai\Delivery\DeliveryClient;

$client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7');

// Gets navigation items and their linked items
$root = $client->getItem('root_navigation_item', (new QueryParams())
            ->depth(5));

// Gets specific elements of all articles
$articles = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')
            ->elements(array("title", "url")));
    • cURL
    # Gets navigation items and their linked items
curl --request GET \
  --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items/root_navigation_item?depth=5' \
  --header 'content-type: application/json'

# Gets specific elements of all articles
curl --request GET \
  --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items?system.type=article&elements=title%2Curl' \
  --header 'content-type: application/json'
    # Gets navigation items and their linked items
curl --request GET \
  --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items/root_navigation_item?depth=5' \
  --header 'content-type: application/json'

# Gets specific elements of all articles
curl --request GET \
  --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items?system.type=article&elements=title%2Curl' \
  --header 'content-type: application/json'
    • Ruby
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby
require 'delivery-sdk-ruby'

delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7'
# Gets navigation items and their linked items
delivery_client.item('root_navigation_item')
               .depth(5)
               .execute do |response|
                 item = response.item
               end

# Gets specific elements of all articles
delivery_client.items('system.type'.eq('article'))
               .elements(%w[title url])
               .execute do |response|
                 items = response.items
               end
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby
require 'delivery-sdk-ruby'

delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7'
# Gets navigation items and their linked items
delivery_client.item('root_navigation_item')
               .depth(5)
               .execute do |response|
                 item = response.item
               end

# Gets specific elements of all articles
delivery_client.items('system.type'.eq('article'))
               .elements(%w[title url])
               .execute do |response|
                 items = response.items
               end
    • TypeScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';
import { Article } from './models/Article';
import { NavigationItem } from './models/NavigationItem';

const deliveryClient = createDeliveryClient({
  environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

// Gets navigation items and their linked items
let root: NavigationItem;

const rootResponse = await deliveryClient.item<NavigationItem>('root_navigation_item')
  .depthParameter(5)
  .toPromise();

root = rootResponse.data.item;

// Gets specific elements of all articles
let articles: Article[];

const articleResponse = await deliveryClient.items<Article>()
  .type('article')
  .elementsParameter(['title', 'url'])
  .toPromise();

articles = articleResponse.data.items;
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';
import { Article } from './models/Article';
import { NavigationItem } from './models/NavigationItem';

const deliveryClient = createDeliveryClient({
  environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

// Gets navigation items and their linked items
let root: NavigationItem;

const rootResponse = await deliveryClient.item<NavigationItem>('root_navigation_item')
  .depthParameter(5)
  .toPromise();

root = rootResponse.data.item;

// Gets specific elements of all articles
let articles: Article[];

const articleResponse = await deliveryClient.items<Article>()
  .type('article')
  .elementsParameter(['title', 'url'])
  .toPromise();

articles = articleResponse.data.items;

    5. Display navigation

    Using the retrieved data, display the navigation as you prefer. It can be your sections in a mobile app or smartwatch, or it can be a menu on a website like this:

    The content of the linked items is inside the modular_content property of the response.

    And that's it! You now have a dynamic menu that your content creators can manage entirely from Kontent.ai.

    Microsites and proofs of concept

    If you're building a microsite or just a quick proof of concept and need navigation fast, you can hardcode the navigation. No part of your navigation is modeled in Kontent.ai; it's all in the source code. See our sample application as an example. We discourage using hardcoded navigation for larger live projects.

    What's next?