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

You can extend the standard menu by implementing a menu provider as an alternative to attributes. The menu provider returns menu items that are correctly localized. To use a menu provider, implement the IMenuProvider interface, decorate it with the [MenuProvider] attribute, and make it part of a registered shell module.

Adding menu items

You can add menu sections and sub-menu items such as menu sections, drop-downs, URLs and pop-up menu items. Each menu item defines a path which determines 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 SectionMenuItem("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 };
    }
}

Localizing menu items with a menu provider

A menu provider returns localized menu items.

Permissions with the menu provider

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.

Flow of menu items

Menu items flow from the providers 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>

Do you find this information helpful? Yes No

Why wasn't this helpful? (check all that apply) Couldn't find what I was looking for Instructions confusing or unclear Instructions didn't work

Please tell us more! (optional)

We're doing our best to answer your questions in the documentation. If we have not, please explain what you are looking for.

If possible, provide your email address. We may contact you to fully understand your comments and update the documentation accordingly.

Email address (optional):

Last updated: Sep 11, 2019