Extending the navigation

Table of contents

• Introduction
• Using menu providers

Introduction

OnlineCenter is equipped with extendable navigation. This allows EPiServer CMS and other products to be accessed by editors from the top menu. The preferred way of adding an interface to the menu is using the [MenuItem] attribute. Other options include configuration and implementing a custom menu provider. Both attributes and menu providers needs to reside in an assembly configured as a shell module.

[MenuItem] Attribute

Menu item is an attribute used on ASP.NET MVC controllers and WebForm pages. This attribute adds links to the top menu (requires the module to be registered, see Shell Modules). The required parameter menuPath is a logical path of the menu element in the menu. The URL to the actual interface to link to is added using the Url parameter.

Example (WebForm page):

[MenuItem("/global/cms/edit", Text = "Edit", Url = 
            "Path/To/Default.aspx")]
            public partial class DefaultPage : SystemPageBase
            {
            }

This adds a menu item to the CMS menu section with the text Edit and the URL /[PublicOrProtected]/[ModuleName]/Path/To/Default.aspx.

Example (MVC action):

public class DashboardController : Controller
            {
    [MenuItem("/global/dashboard", Text = "Start")]
    public ActionResult Index()
    {
    }
            }

This adds a menu item to the top menu bar with the text Start and the URL is inferred from the ASP.NET MVC route table.

Localization

Localization of menu items defined with attributes is done via a static property of a resource class. ResourceType references a class with a static property. TextResourceKey is the name of the static property that returns the localized text.

Example:

Menu path

To organize menu items in a tree structure the menu path is used. All menu items in the top menu are in the “/global” bucket. The next segment is the name of menu section, for example, “/global/cms”. The last segment represents the actual user interface, for example, “/global/cms/edit”.

URL

Some menu items have an URL. This creates a link in the menu. The page at the end of this URL should render a menu where the corresponding menu path is selected.

Permissions

You can restrict who sees a certain menu item by using the [Authorize] attribute.

Example:

public class DashboardController : Controller
            {
    [MenuItem("/global/dashboard")]
    [Authorize(Roles = "NoOne")]
    public ActionResult Index()
    {
    }
            }

Using menu providers

The building blocks of the navigation are menu providers and menu items. A menu provider provides an enumeration of menu items which are organized in a tree according to their menu path. EPiServer CMS contains a menu provider that looks at [MenuItem] attributes and provides them as menu items.

IMenuProvider

A slightly more technical alternative to attributes to extend the standard menu is implementing a menu provider. The menu provider is responsible for returning menu items that are correctly localized. For a menu provider to be used it needs to implement the IMenuProvider interface, be decorated with the [MenuProvider] attribute and be part of a registered shell module.

Menu items

It is possible to add menu sections and sub-menu items. The types supported are menu sections, drop-downs, URLs and pop-up menu items. Each menu item defines a path which decides its location in the menu hierarchy. For example, a URL menu item with path /global/cms/myMenu is placed in the CMS section of the menu (which has the path /global/cms).

Types:

• URL Menu Item are links, a click navigates to specified URL
• Popup Menu Item are links opened in a popup window (javascript window.open)
• Section Menu Item are top menu sections which open an underlying menu
• Drop-Down Menu Item are drop-down style menu items designed for the utility menu area (right)

Example:

/// <summary>
            /// Provides menu items for the CMS product.
            /// </summary>
            [MenuProvider]
            public class CmsMenuProvider : IMenuProvider
            {
    /// <summary>
    /// Provides the CMS menu section and the CMS settings section.
    /// </summary>
    /// <returns>
    /// A list of <see cref="MenuItem"/>s that the provider exposes.
    /// </returns>
    public IEnumerable<MenuItem> GetMenuItems()
    {
        // Create the top menu section
        var section = new MenuSection("CMS", // Title

            "/global/cms"); // Logical path
        // Visible to CMS editors
        section.IsAvailable = (request) => 
            PrincipalInfo.HasEditAccess;

        // Create the edit menu item below the top 
            section
        var cmsEdit = new UrlMenuItem("Edit", // Title

            "/global/cms/edit", // Logical path

            "/path/to/edit/default.aspx"); // URL
        // Visible to CMS editors
        cmsEdit.IsAvailable = (request) => 
            PrincipalInfo.HasEditAccess;
        return new MenuItem[] { section, cmsEdit };
    }
            }

Localization

A menu provider is responsible for returning localized menu items.

Permissions

The menu provider can defer permission filtering to the menu item by setting the “IsAvailable” delegate to a method that checks access for the user provided with the RequestContext parameter.

Example:

Flow of menu Items

Menu items flow from the providers to into a hierarchical model which is rendered into HTML.

Configuring web.config

To extend the menu you can, for example, configure web.config as follows:

<episerver.shell>
    <navigation>
      <add text="Intranet" menuPath="/global/intra" 
            url="http://intra" sortIndex="100" />
      <add text="My section" menuPath="/global/my" 
            menuItemType="Section" sortIndex="300" />
      <add text="Edit" menuPath="/global/my/edit" 
            url="/my/edit.aspx" sortIndex="100" />
      <add text="Admin" menuPath="/global/my/admin" 
            url="/my/admin.aspx" sortIndex="200" />
    </navigation>
</episerver.shell>