Displays a menu in an ASP.NET Web page.
Assembly: System.Web (in System.Web.dll)
[ControlValuePropertyAttribute(L"SelectedValue")] [AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)] [AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)] public ref class Menu : public HierarchicalDataBoundControl, IPostBackEventHandler, INamingContainer
The control is used to display a menu in an ASP.NET Web page and is often used in combination with a SiteMapDataSource control for navigating a Web site. The 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 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 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 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 control. To display the linked content in a different window or frame, use the Target property of the control.
The control displays two types of menus: a static menu and a dynamic menu. The static menu is always displayed in a 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.
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.
The control is not designed to be used inside an UpdatePanel control. You can add the control only to a page outside an UpdatePanel control. UpdatePanel controls are used to update selected regions of a page instead of updating the whole page with a postback. For more information, see UpdatePanel Control Overview and Partial-Page Rendering Overview.
A 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 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.
If the NavigateUrl property is not set for a menu item, the 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.
The simplest data model of the 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 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 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 control to the ID value of the data source control. The control automatically binds to the specified data source control. This is the preferred method to bind to data.
When a menu item binds to a data source where each data item contains multiple properties (such as an XML element with several attributes), the 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 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 control creates a default binding using the DataSource property. For more information, see Binding to Databases.
Customizing the User Interface
There are many ways to customize the appearance of the control. First, you can specify whether the 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 Web Server Controls and CSS Styles.
The following table lists the available menu item styles.
Menu item style property
The style settings for a dynamic menu item when the mouse pointer is positioned over it.
The style settings for an individual dynamic menu item.
The style settings for a dynamic menu.
The style settings for the currently selected dynamic menu item.
The style settings for a static menu item when the mouse pointer is positioned over it.
The style settings for an individual static menu item.
The style settings for a static menu.
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
A collection of MenuItemStyle objects that control the style of the menu items on a level basis.
A collection of MenuItemStyle objects that control the style of selected menu items on a level basis.
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.
If you use any of the level style collections listed in the previous table to define the style for the 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 control. You can specify your own custom image for the different parts of the control by setting the properties shown in the following table.
An optional image displayed at the bottom of a dynamic menu item to separate it from other menu items.
An optional image displayed in a dynamic menu item to indicate that it has a submenu.
An optional image displayed at the top of a dynamic menu item to separate it from other menu items.
The image displayed at the bottom of a menu item to indicate that the user can scroll down to view additional menu items.
The image displayed at the top of a menu item to indicate that the user can scroll up to view additional menu items.
An optional image displayed at the bottom of a static menu item to separate it from other menu items.
An optional image displayed in a static menu item to indicate that it has a submenu.
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 control using the following template properties.
The template that contains the custom content to render for a dynamic menu item.
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.
The 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.
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 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.
A Visual Studio Web site project with source code is available to accompany this topic: Download.
The following code example demonstrates how to create a control with static menu items using declarative syntax.
The following code example demonstrates how to bind the 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.
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>
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.