Loading...
Area: Episerver CMS
Applies to versions: 10 and higher
Other versions:

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>

Last updated: Sep 11, 2019