In this topic:

• Introduction

• Menu Items

• Static Data

• Binding to Data

• Customizing the User Interface

• Events

• Accessibility

• Declarative Syntax

The System.Web.UI.WebControls.Menu control is used to display a menu in an ASP.NET Web page and is often used in combination with a System.Web.UI.WebControls.SiteMapDataSource control for navigating a Web site. The System.Web.UI.WebControls.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 System.Web.UI.WebControls.SiteMapDataSource control.

• Programmatic access to the System.Web.UI.WebControls.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 System.Web.UI.WebControls.Menu control can either navigate to a linked Web page or simply post back to the server. If the MenuItem.NavigateUrl property of a menu item is set, the System.Web.UI.WebControls.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 System.Web.UI.WebControls.Menu control. To display the linked content in a different window or frame, use the Menu.Target property of the System.Web.UI.WebControls.Menu control.

The System.Web.UI.WebControls.Menu control displays two types of menus: a static menu and a dynamic menu. The static menu is always displayed in a System.Web.UI.WebControls.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 Menu.StaticDisplayLevels property. Menu items (if any) with a higher level than the value specified by the Menu.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 Menu.DisappearAfter property to specify the duration.

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

A System.Web.UI.WebControls.Menu control is made up of a tree of menu items represented by System.Web.UI.WebControls.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 Menu.Items collection. Child menu items are stored in a parent menu item's MenuItem.ChildItems collection.

Each menu item has a MenuItem.Text and a MenuItem.Value property. The value of the MenuItem.Text property is displayed in the System.Web.UI.WebControls.Menu control, while the MenuItem.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 MenuItem.NavigateUrl property.

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

For more information on menu items, see System.Web.UI.WebControls.MenuItem.

The simplest data model of the System.Web.UI.WebControls.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 System.Web.UI.WebControls.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 System.Web.UI.WebControls.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.

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

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 Menu.DataBindings collection to specify menu item bindings. The Menu.DataBindings collection contains System.Web.UI.WebControls.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 System.Web.UI.WebControls.MenuItemBinding.

You cannot create empty nodes in a System.Web.UI.WebControls.Menu control by setting the MenuItemBinding.Text or MenuItemBinding.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 System.Web.UI.WebControls.Menu control creates a default binding using the BaseDataBoundControl.DataSource property. For more information, see Binding to Databases.

There are many ways to customize the appearance of the System.Web.UI.WebControls.Menu control. First, you can specify whether the System.Web.UI.WebControls.Menu control is rendered horizontally or vertically by setting the Menu.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 Web Server Controls and CSS Styles.

The following table lists the available menu item styles.

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.

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.

Another way to alter the appearance of the control is to customize the images displayed in the System.Web.UI.WebControls.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.

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

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

The System.Web.UI.WebControls.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.

For information about how to configure this control so that it generates markup that conforms to accessibility standards, see Accessibility in Visual Studio 2010 and ASP.NET 4 and ASP.NET Controls and Accessibility.

<asp:Menu
    AccessKey="string"
    BackColor="color name|#dddddd"
    BorderColor="color name|#dddddd"
    BorderStyle="