Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Menu Class

Displays a menu in a Web Forms page.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

[ControlValuePropertyAttribute("SelectedValue")] 
public class Menu : HierarchicalDataBoundControl, IPostBackEventHandler, INamingContainer
/** @attribute ControlValuePropertyAttribute("SelectedValue") */ 
public class Menu extends HierarchicalDataBoundControl implements IPostBackEventHandler, INamingContainer
ControlValuePropertyAttribute("SelectedValue") 
public class Menu extends HierarchicalDataBoundControl implements IPostBackEventHandler, INamingContainer
Not applicable.

The Menu control is used to display a menu in a Web Forms page and is often used in combination with a SiteMapDataSource control for navigating a Web site. The Menu control supports the following features:

  • Data binding that allows the control's menu items to be bound to hierarchal data sources.

  • Site navigation through integration with the SiteMapDataSource control.

  • Programmatic access to the Menu object model to dynamically create menus, populate menu items, set properties, and so on.

  • Customizable appearance through themes, user-defined images, styles, and user-defined templates.

When the user clicks a menu item, the Menu control can either navigate to a linked Web page or simply post back to the server. If the NavigateUrl property of a menu item is set, the Menu control navigates to the linked page; otherwise, it posts the page back to the server for processing. By default, a linked page is displayed in the same window or frame as the Menu control. To display the linked content in a different window or frame, use the Target property of the Menu control.

NoteNote:

The Target property affects every menu item in the control. To specify a window or frame for an individual menu item, set the Target property of the MenuItem object directly.

The Menu control displays two types of menus: a static menu and a dynamic menu. The static menu is always displayed in a Menu control. By default, the menu items at the root level (level 0) are displayed in the static menu. You can display additional menu levels (static submenus) within the static menu by setting the StaticDisplayLevels property. Menu items (if any) with a higher level than the value specified by the StaticDisplayLevels property are displayed in a dynamic menu. A dynamic menu appears only when the user positions the mouse pointer over the parent menu item that contains a dynamic submenu. Dynamic menus automatically disappear after a certain duration. Use the DisappearAfter property to specify the duration.

NoteNote:

A dynamic menu also disappears when the user clicks outside of the menu.

You can also limit the number of levels displayed in a dynamic menu by setting the MaximumDynamicDisplayLevels property. Menu levels higher than the specified value are discarded.

Menu Items

A Menu control is made up of a tree of menu items represented by MenuItem objects. Menu items at the top level (level 0) are called root menu items. A menu item that has a parent menu item is called a child menu item. All root menu items are stored in the Items collection. Child menu items are stored in a parent menu item's ChildItems collection.

Each menu item has a Text and a Value property. The value of the Text property is displayed in the Menu control, while the Value property is used to store any additional data about the menu item, such as data passed to the postback event associated with the menu item. When clicked, a menu item can navigate to another Web page indicated by the NavigateUrl property.

NoteNote:

If the NavigateUrl property is not set for a menu item, the Menu control simply submits the page to the server for processing when the menu item is clicked.

You can also optionally display an image in a menu item by setting the ImageUrl property.

For more information on menu items, see MenuItem.

Static Data

The simplest data model of the Menu control is static menu items. To display static menu items using declarative syntax, first nest opening and closing <Items> tags between the opening and closing tags of the Menu control. Next, create the menu structure by nesting <asp:MenuItem> elements between the opening and closing <Items> tags. Each <asp:MenuItem> element represents a menu item in the control and maps to a MenuItem object. You can set the properties of each menu item by setting the attributes of its <asp:MenuItem> element. To create submenu items, nest additional <asp:MenuItem> elements between the opening and closing <asp:MenuItem> tags of the parent menu item.

Binding to Data

The Menu control can also be bound to data. You can use either of two methods to bind the Menu control to the appropriate data source type:

  • The Menu control can use any hierarchal data source control, such as an XmlDataSource control or a SiteMapDataSource control. To bind to a hierarchal data source control, set the DataSourceID property of the Menu control to the ID value of the data source control. The Menu control automatically binds to the specified data source control. This is the preferred method to bind to data.

  • The Menu control can also be bound to an XmlDocument object. To bind to this data source, set the DataSource property of the Menu control to the data source and then call the DataBind method.

When binding to a data source where each data item contains multiple properties (such as an XML element with several attributes), a menu item displays the value returned by the ToString method of the data item by default. In the case of an XML element, the menu item displays the element name, which shows the underlying structure of the menu tree but is not very useful otherwise. You can bind a menu item to a specific data item property by using the DataBindings collection to specify menu item bindings. The DataBindings collection contains MenuItemBinding objects that define the relationship between a data item and the menu item it is binding to. You can specify the criteria for binding and the data item property to display in the node. For more information on menu item bindings, see MenuItemBinding.

You cannot create empty nodes in a Menu control by setting the Text or TextField properties to the empty string (""). Setting these properties to the empty string has the same effect as not setting the properties. In that case, the Menu control creates a default binding using the DataSource property. For more information, see Web Page Data Binding Techniques.

Customizing the User Interface

There are many ways to customize the appearance of the Menu control. First, you can specify whether the Menu control is rendered horizontally or vertically by setting the Orientation property. You can also specify a different style (such as font size and color) for each of the menu item types.

If you use cascading style sheets (CSS) to customize the appearance of the control, use either inline styles or a separate CSS file, but not both. Using both inline styles and a separate CSS file could cause unexpected results. For more information on using style sheets with controls, see ASP.NET Server Controls and CSS Styles (Visual Studio).

The following table lists the available menu item styles.

Menu item style property

Description

DynamicHoverStyle

The style settings for a dynamic menu item when the mouse pointer is positioned over it.

DynamicMenuItemStyle

The style settings for an individual dynamic menu item.

DynamicMenuStyle

The style settings for a dynamic menu.

DynamicSelectedStyle

The style settings for the currently selected dynamic menu item.

StaticHoverStyle

The style settings for a static menu item when the mouse pointer is positioned over it.

StaticMenuItemStyle

The style settings for an individual static menu item.

StaticMenuStyle

The style settings for a static menu.

StaticSelectedStyle

The style settings for the currently selected static menu item.

Instead of setting the individual style properties, you can specify styles that are applied to menu items based on their level by using the following style collections.

Level style collections

Description

LevelMenuItemStyles

A collection of MenuItemStyle objects that control the style of the menu items on a level basis.

LevelSelectedStyles

A collection of MenuItemStyle objects that control the style of selected menu items on a level basis.

LevelSubMenuStyles

A collection of MenuItemStyle objects that control the style of the submenu items on a level basis.

The first style in the collection corresponds to the style of the menu items at the first depth level in the menu tree. The second style in the collection corresponds to the style of the menu items at the second depth level in the menu tree, and so on. This is most often used to generate table of contents-style navigation menus where menu items at a certain depth should have the same appearance, regardless of whether they have submenus.

NoteNote:

If you use any of the level style collections listed in the previous table to define the style for the Menu control, these style settings override the individual menu item style properties.

Another way to alter the appearance of the control is to customize the images displayed in the Menu control. You can specify your own custom image for the different parts of the control by setting the properties shown in the following table.

Image property

Description

DynamicBottomSeparatorImageUrl

An optional image displayed at the bottom of a dynamic menu item to separate it from other menu items.

DynamicPopOutImageUrl

An optional image displayed in a dynamic menu item to indicate that it has a submenu.

DynamicTopSeparatorImageUrl

An optional image displayed at the top of a dynamic menu item to separate it from other menu items.

ScrollDownImageUrl

The image displayed at the bottom of a menu item to indicate that the user can scroll down to view additional menu items.

ScrollUpImageUrl

The image displayed at the top of a menu item to indicate that the user can scroll up to view additional menu items.

StaticBottomSeparatorImageUrl

An optional image displayed at the bottom of a static menu item to separate it from other menu items.

StaticPopOutImageUrl

An optional image displayed in a static menu item to indicate that it has a submenu.

StaticTopSeparatorImageUrl

An optional image displayed at the top of a static menu item to separate it from other menu items.

For complete control of the user interface (UI), you can define your own custom templates for the Menu control using the following template properties.

Template property

Description

DynamicItemTemplate

The template that contains the custom content to render for a dynamic menu item.

StaticItemTemplate

The template that contains the custom content to render for a static menu item.

You can control the vertical and horizontal position of a dynamic menu relative to its parent menu item by setting the DynamicVerticalOffset and DynamicHorizontalOffset properties, respectively. To control the indentation of the static submenu items within a static menu, use the StaticSubMenuIndent property.

Events

The Menu control provides several events that you can program against. This allows you to run a custom routine whenever an event occurs. The following table lists the supported events.

Event

Description

MenuItemClick

Occurs when a menu item is clicked. This event is commonly used to synchronize a Menu control with another control on the page.

MenuItemDataBound

Occurs when a menu item is bound to data. This event is commonly used to modify a menu item before it is rendered in a Menu control.

Accessibility

The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.

The Menu control provides the SkipLinkText property as a way for the entire control to be skipped by screen readers. If the SkipLinkText property is set, an invisible image with alternate text is rendered, giving the user the option to jump to the end of the control. Screen readers read the alternate text aloud, and the image occupies only one pixel space. For pixel-precise control over the rendering of the page, set the SkipLinkText property to an empty string ("") and provide your own mechanism to skip the menu. The SkipLinkText property is set to the empty string by default.

TopicLocation
How to: Programmatically Enumerate Site-Map NodesBuilding ASP .NET Web Applications
How to: Configure Multiple Site Maps and Site-Map ProvidersBuilding ASP .NET Web Applications
How to: Filter the Nodes Retrieved by SiteMapDataSource Web Server ControlsBuilding ASP .NET Web Applications
How to: Customize the Appearance of SiteMapPath Web Server ControlsBuilding ASP .NET Web Applications
How to: Display Site-Map Data in Non-Hierarchical Web Server ControlsBuilding ASP .NET Web Applications
How to: Add Simple Site NavigationBuilding ASP .NET Web Applications
How to: Implement ASP.NET Site-Map ProvidersBuilding ASP .NET Web Applications
How to: Programmatically Enumerate Site-Map NodesBuilding ASP .NET Web Applications
How to: Configure Multiple Site Maps and Site-Map ProvidersBuilding ASP .NET Web Applications
How to: Filter the Nodes Retrieved by SiteMapDataSource Web Server ControlsBuilding ASP .NET Web Applications
How to: Customize the Appearance of SiteMapPath Web Server ControlsBuilding ASP .NET Web Applications
How to: Display Site-Map Data in Non-Hierarchical Web Server ControlsBuilding ASP .NET Web Applications
How to: Add Simple Site NavigationBuilding ASP .NET Web Applications
How to: Implement ASP.NET Site-Map ProvidersBuilding ASP .NET Web Applications
Walkthrough: Adding Site Navigation to a Web SiteBuilding ASP .NET Web Applications in Visual Studio
Walkthrough: Controlling ASP.NET Menus ProgrammaticallyBuilding ASP .NET Web Applications in Visual Studio
Walkthrough: Displaying a Menu on Web PagesBuilding ASP .NET Web Applications in Visual Studio
How to: Add Simple Site NavigationBuilding ASP .NET Web Applications in Visual Studio

The following code example demonstrates how to create a Menu control with static menu items using declarative syntax.


<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >

  <!-- For the hover styles of the Menu control to  -->
  <!-- work correctly, you must include this head   -->
  <!-- element.                                     -->
  <head runat="server">
    <title>Menu Declarative Example</title>
</head>

  <body>
    <form id="form1" runat="server">
    
      <h3>Menu Declarative Example</h3>
    
      <!-- Use declarative syntax to create the   -->
      <!-- menu structure. Submenu items are      -->
      <!-- created by nesting them in parent menu -->
      <!-- items.                                 -->
      <asp:menu id="NavigationMenu"
        disappearafter="2000"
        staticdisplaylevels="2"
        staticsubmenuindent="10" 
        orientation="Vertical"
        font-names="Arial" 
        target="_blank"  
        runat="server">
        
        <staticmenuitemstyle backcolor="LightSteelBlue"
          forecolor="Black"/>
        <statichoverstyle backcolor="LightSkyBlue"/>
        <dynamicmenuitemstyle backcolor="Black"
          forecolor="Silver"/>
        <dynamichoverstyle backcolor="LightSkyBlue"
          forecolor="Black"/>
      
        <items>
          <asp:menuitem navigateurl="Home.aspx" 
            text="Home"
            tooltip="Home">
            <asp:menuitem navigateurl="Music.aspx"
              text="Music"
              tooltip="Music">
              <asp:menuitem navigateurl="Classical.aspx" 
                text="Classical"
                tooltip="Classical"/>
              <asp:menuitem navigateurl="Rock.aspx"
                text="Rock"
                tooltip="Rock"/>
              <asp:menuitem navigateurl="Jazz.aspx"
                text="Jazz"
                tooltip="Jazz"/>
            </asp:menuitem>
            <asp:menuitem navigateurl="Movies.aspx"
              text="Movies"
              tooltip="Movies">
              <asp:menuitem navigateurl="Action.aspx"
                text="Action"
                tooltip="Action"/>
              <asp:menuitem navigateurl="Drama.aspx"
                text="Drama"
                tooltip="Drama"/>
              <asp:menuitem navigateurl="Musical.aspx"
                text="Musical"
                tooltip="Musical"/>
            </asp:menuitem>
          </asp:menuitem>
        </items>
      
      </asp:menu>

    </form>
  </body>
</html>


The following code example demonstrates how to bind the Menu control to a SiteMapDataSource control. For this example to work correctly, you must copy the sample site map data below to a file named Web.sitemap.


<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >

  <!-- For the hover styles of the Menu control to  -->
  <!-- work correctly, you must include this head   -->
  <!-- element.                                     -->
  <head runat="server">
    <title>Menu DataBinding Example</title>
</head>

  <body>
    <form id="form1" runat="server">
    
      <h3>Menu DataBinding Example</h3>
    
      <!-- Bind the Menu control to a SiteMapDataSource control.  -->
      <asp:menu id="NavigationMenu"
        disappearafter="2000"
        staticdisplaylevels="2"
        staticsubmenuindent="10" 
        orientation="Vertical"
        font-names="Arial" 
        target="_blank"
        datasourceid="MenuSource"   
        runat="server">
        
        <staticmenuitemstyle backcolor="LightSteelBlue"
          forecolor="Black"/>
        <statichoverstyle backcolor="LightSkyBlue"/>
        <dynamicmenuitemstyle backcolor="Black"
          forecolor="Silver"/>
        <dynamichoverstyle backcolor="LightSkyBlue"
          forecolor="Black"/>

      </asp:menu>
      
      <asp:SiteMapDataSource id="MenuSource"
        runat="server"/>        

    </form>
  </body>
</html>


The following is sample site map data for the previous example.

<siteMap>

<siteMapNode url="~\Home.aspx"

title="Home"

description="Home">

<siteMapNode url="~\Music.aspx"

title="Music"

description="Music">

<siteMapNode url="~\Classical.aspx"

title="Classical"

description="Classical"/>

<siteMapNode url="~\Rock.aspx"

title="Rock"

description="Rock"/>

<siteMapNode url="~\Jazz.aspx"

title="Jazz"

description="Jazz"/>

</siteMapNode>

<siteMapNode url="~\Movies.aspx"

title="Movies"

description="Movies">

<siteMapNode url="~\Action.aspx"

title="Action"

description="Action"/>

<siteMapNode url="~\Drama.aspx"

title="Drama"

description="Drama"/>

<siteMapNode url="~\Musical.aspx"

title="Musical"

description="Musical"/>

</siteMapNode>

</siteMapNode>

</siteMap>

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft