Upgrade global navigation menu

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

Migrate your views from legacy menu rendering to the shared CommonLayout.cshtml, which handles navigation rendering and positioning automatically.

📘
Note
The navigation menu is built for Optimizely Content Management System (CMS), but other products and add-ons must opt in. When you use the shared CommonLayout, your add-on gets CMS UI navigation automatically.

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

Update the view

Replace legacy rendering calls such as @Html.Raw(Html.GlobalMenu()), @Html.CreatePlatformNavigationMenu(), or manual tag helpers with CommonLayout.cshtml. The layout renders the navigation bar through the <platform-navigation /> tag helper and positions content automatically.

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, and so on).
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 -->
}

View with client resources

The following example uses 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

Understand what CommonLayout.cshtml handles so you do not duplicate rendering logic. The layout includes the following components 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.

The layout eliminates the need to render navigation components or handle navigation spacing manually.

Update styles (optional)

CMS UI styling aligns with the navigation bar. If your add-on uses custom styling, update it to match the current navigation appearance.