Upgrade global navigation menu

Describes how to upgrade your views to use the shared CommonLayout for rendering the global navigation menu in Optimizely CMS.

📘
Note
The navigation menu is introduced for CMS, but other products and add-ons must opt in. If you use the shared CommonLayout, your add-on gets the CMS UI navigation automatically.

If you implement the navigation for the first time instead of upgrading, see Add and configure menu items.

Update the view

Replace legacy navigation rendering (@Html.Raw(Html.GlobalMenu()), @Html.CreatePlatformNavigationMenu(), or manual tag helpers) with the shared CommonLayout.cshtml. The layout handles navigation rendering and positioning automatically using the <platform-navigation /> tag helper.

Set the layout and define three sections in your view:

title – Sets the page <title>. Falls back to "CMS" if omitted.
header – Content injected into the <head> tag (stylesheets, scripts, etc.).
mainContent – Your page content, rendered inside a <platform-navigation-wrapper> that accounts for the fixed navigation bar.

@{
    Layout = "/CmsUIViews/Views/Shared/CommonLayout.cshtml";
}

@section title
{
    <title>My Title</title>
}

@section header
{
    <!-- Stylesheets and head scripts go here -->
}

@section mainContent
{
    <!-- Page content goes here -->
}

Example

Below is an example view using CommonLayout with client resources:

@model MyViewModel
@{
    Layout = "/CmsUIViews/Views/Shared/CommonLayout.cshtml";
}
@using EPiServer.Framework.Web.Resources

@addTagHelper *, EPiServer.Shell.UI

@section title
{
    <title>Optimizely CMS - @Model.Title</title>
}

@section header
{
    @ClientResources.RenderResources("my-module", new[] { ClientResourceType.Style })
}

@section mainContent
{
    <div id="root" data-epi-module-url="@Model.ModuleUrl"></div>

    @ClientResources.RenderResources("my-module", new[] { ClientResourceType.Script })
}

What the layout provides

The CommonLayout.cshtml layout includes the following automatically:

<platform-navigation /> – A tag helper that renders the global navigation bar.
<platform-navigation-wrapper> – Wraps your mainContent section, ensuring content is not hidden behind the fixed navigation.
Anti-forgery token – Injected via @Html.AntiForgeryToken().
Standard meta tags and favicon – Charset, viewport, and favicon configuration.
Client resources – CMS head and body resource bundles.

You do not need to manually render navigation components or handle navigation spacing in your view.

Update styles (optional)

CMS UI has updated its styling to align with the navigation. If you have custom styling, update your styles to match the current navigation appearance.

Updated about 20 hours ago