Control

<asp:Menu> Control

Navigation between pages of a Web site is conventionally set up with standard <a> anchor tags linked to the various pages. Often, this set of tags is enclosed inside a menu section on a page and duplicated across all pages that shares these navigational links. Of course, when using master pages, this set of links can be created one time only on the master page for display on all associated content pages.

It is not unusual that Web site navigation links change over time as new pages are added to a site, old pages are removed, and other pages are shifted around. There is routine need, then, to reconfigure these links. In this sense, navigation links are no different from other content information maintained for the Web site. They represent dynamic data that change over time. As such, there is convenience in being able to maintain this information apart from the pages on which it appears. Maintaining the navigational structure of a Web site in an external data store, rather than hard coded on the page, enhances the ability to keep it up to date.

ASP.NET 2.0 introduces the <asp:Menu> control to help manage the navigational structure of a Web site. It is used to create static links, much like hard coding <a> tags; it also permits maintenance of a site's navigational links in an external file for convenience in changing the links and, effectively, changing the structure of the site.

Creating a Navigation Menu

The navigational structure of a Web site is defined with an <asp:Menu> control in the general format shown in Figure 12-6. Certain of the property settings pertain to static menu items that are always displayed; others pertain to dynamic menu items displayed in "PopOut" submenus. Also, some of the items are pertinent when hard coding menu items, and others when binding the Menu to an external data source.

<asp:Menu id="id" Runat="Server"   DataSourceID="id"   DisappearAfter="milliseconds"   DynamicBottomSeparatorImageUrl="url"   DynamicEnableDefaultPopOutImage="False|True"   DynamicHorizontalOffset="n"   DynamicItemFormatString="{string}"   DynamicPopOutImageTextFormatString="{string}"   DynamicPopOutImageUrl="url"   DynamicTopSeparatorImageUrl="url"   DynamicVerticalOffset="n"   ItemWrap="False|True"   MaximumDynamicDisplayLevels="n"   Orientation="Horizontal|Vertical"   ScrollDownImageUrl="url"   ScrollDownText="string"   ScrollUpImageUrl="url"   ScrollUpText="string"   StaticBottomSeparatorImageUrl="url"   StaticDisplayLevels="n"   StaticEnableDefaultPopOutImage="False|True"   StaticItemFormatString="{string}"   StaticPopOutImageTextFormatString="{string}"   StaticPopOutImageUrl="url"   StaticSubMenuIndent="n"   StaticTopSeparatorImageUrl="url"   Target="_blank|_parent|_search|_self|_top|framename"             DynamicHoverStyle-property="value"...     DynamicMenuItemStyle-property="value"...     DynamicSelectedStyle-property="value"...     DynamicMenuStyle-property="value"...     StaticHoverStyle-property="value"...    StaticMenuStyle-property="value"...     StaticMenuItemStyle-property="value"...     StaticSelectedStyle-property="value"... >            <Items>             <asp:MenuItem       DataItem="field"       DataPath="path"       ImageUrl="url"       NavigateUrl="url"       PopOutImageUrl="url"       Selectable="False|True"       Selected="False|True"       SeparatorImageUrl="url"       Target="_blank|_parent|_search|_self|_top|framename"       Text="string"       Value="string"       ValuePath="path"     />     ...                  </Items>           <DataBindings>       <asp:MenuItemBinding       TextField="field"       ValueField="field"       NavigateUrlField="field"       Target="_blank|_parent|_search|_self|_top|framename"     />     </DataBindings>   </asp:Menu>

Figure 12-6. General format for <asp:Menu> control.

Creating a Static Menu

A static menu is created by coding an <asp:Menu> control inside of which is a set of menu items contained inside an <Items> section. Individual menu items are identify by <asp:MenuItem> controls containing link and display information. The following example shows a simple two-level set of menu items appearing on a master page to load content pages.

Figure 12-7. Basic navigation menu.

Code for this set of basic navigation links is shown in Listing 12-5. Each menu item is defined by an <asp:MenuItem> control. To establish submenus, as in this example, <asp:MenuItem> child controls representing submenu items are nested inside their parent <asp:MenuItem> controls.

<%@ Master %>

<html>

<head>

  <title>Web Site</title>

</head>

<body>

<form Runat="Server">

<table border="1">

<tr>

  <td style="width:100px; vertical-align:top; background-color:#E0E0E0">

  <b>Menu</b><br/>

  <asp:Menu id="NavigationMenu" Runat="Server"

    StaticDisplayLevels="2">

    <Items>

    <asp:MenuItem Text="Page 1" NavigateUrl="Page1.aspx">

      <asp:MenuItem Text="Page 1-1" NavigateUrl="Page1-1.aspx"/>

      <asp:MenuItem Text="Page 1-2" NavigateUrl="Page1-2.aspx"/>

    </asp:MenuItem>

    <asp:MenuItem Text="Page 2" NavigateUrl="Page2.aspx">

      <asp:MenuItem Text="Page 2-1" NavigateUrl="Page2-1.aspx"/>

      <asp:MenuItem Text="Page 2-2" NavigateUrl="Page2-2.aspx"/>

    </asp:MenuItem>

    <asp:MenuItem Text="Page 3" NavigateUrl="Page3.aspx">

      <asp:MenuItem Text="Page 3-1" NavigateUrl="Page3-1.aspx"/>

      <asp:MenuItem Text="Page 3-2" NavigateUrl="Page3-2.aspx"/>

    </asp:MenuItem>

    </Items>

  </asp:Menu>

  </td>

  <td style="width:400px; vertical-align:top">

    <asp:ContentPlaceHolder id="CONTENT" Runat="Server"/>

  </td>

</tr>

</table>

</form>

</body>

</html>

Listing 12-5. Code for a Menu control appearing on a master page.

Each MenuItem must contain a Text property to produce a clickable link; it contains a NavigateUrl property to give the absolute or relative URL of the page. By default, only the first level (level 0) of menu items is displayed. If preferred, as in this example, the number of levels to display can be set with the StaticDisplayLevels property of the Menu control. If this property is not set, PopOut menus appear as described below.

This menu appears on the master page for display on all content pages. For this reason, the NavigateURl links probably should be full URLs beginning with "http://". If, for example, the content pages appear in different folders or subfolders, then relative links would be different as various of these pages are loaded; on certain pages the links would not be relative to the particular page. If, however, all content pages are in the same directory, then relative links, as in this example, remain constant.

By default, linked pages are loaded into the same window. An alternate is to supply a Target attribute for the Menu using any of the standard values: "_blank" (new window), "_top" (main browser window), "_search" (the windows search pane), "_self" (current window), "_parent" (parent frame of the current frame in a frameset), or a frame name (in a frameset).

Using Graphic Links

You can use graphic images in place of text links. The following example employs a set of graphic buttons to replace text labels by coding the ImageUrl property rather than the Text property of <asp:MenuItem> controls.

Figure 12-8. Navigation menu using graphic images.

Coding difference between the Menu control for this application and the previous example are shown below. Additional indention of submenus takes place with the StaticSubMenuIndent property and additional vertical spacing between buttons with the VerticalPadding style for menu items.

<asp:Menu id="NavigationMenu" Runat="Server"

  StaticDisplayLevels="2"

  StaticSubMenuIndent="20"

  StaticMenuStyle-VerticalPadding="1">

  <Items>

  <asp:MenuItem ImageUrl="Page1.gif" NavigateUrl="Page1.aspx">

    <asp:MenuItem ImageUrl="Page1-1.gif" NavigateUrl="Page1-1.aspx"/>

    <asp:MenuItem ImageUrl="Page1-2.gif" NavigateUrl="Page1-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem ImageUrl="Page2.gif" NavigateUrl="Page2.aspx">

    <asp:MenuItem ImageUrl="Page2-1.gif" NavigateUrl="Page2-1.aspx"/>

    <asp:MenuItem ImageUrl="Page2-2.gif" NavigateUrl="Page2-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem ImageUrl="Page3.gif" NavigateUrl="Page3.aspx">

    <asp:MenuItem ImageUrl="Page3-1.gif" NavigateUrl="Page3-1.aspx"/>

    <asp:MenuItem ImageUrl="Page3-2.gif" NavigateUrl="Page3-2.aspx"/>

  </asp:MenuItem>

  </Items>

</asp:Menu>

Listing 12-6. Code for a Menu control using graphic images as links.

Styling a Static Menu

You can apply various stylings to menu items. In the following example, StaticSubMenuIndent gives the amount of indention of submenus, vertical padding is added between menu items with a StaticMenuStyle-VerticalPadding, and various font and color styles are applied through StaticMenuItemStyle (normal), StaticHoverStyle (mouse over), and StaticSelectedStyle (selected item) settings.

Figure 12-9. Styled navigation menu.

Code for this application is given below. Note that when any of the "hover" styles (StaticHoverStyle) are applied to visually change a menu item on a mouse-over, the <head> tag for the page must include Runat="Server".

<%@ Master %>

<html>

<head Runat="Server">

  <title>Web Site</title>

</head>

...

<asp:Menu id="NavigationMenu" Runat="Server"

  StaticDisplayLevels="2"

  Width="100"

  StaticSubMenuIndent="10"

  StaticMenuStyle-VerticalPadding="2"

  StaticMenuItemStyle-Font-Name="Verdana"

  StaticMenuItemStyle-Font-Size="9pt"

  StaticMenuItemStyle-ForeColor="#990000"

  StaticHoverStyle-BackColor="#707070"

  StaticHoverStyle-ForeColor="#FFFFFF"

  StaticSelectedStyle-Font-Bold="True"

  StaticSelectedStyle-BackColor="#FFFFFF"

  StaticSelectedStyle-ForeColor="#990000">

  <Items>

  <asp:MenuItem Text="Page 1" NavigateUrl="Page1.aspx">

    <asp:MenuItem Text="Page 1-1" NavigateUrl="Page1-1.aspx"/>

    <asp:MenuItem Text="Page 1-2" NavigateUrl="Page1-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem Text="Page 2" NavigateUrl="Page2.aspx">

    <asp:MenuItem Text="Page 2-1" NavigateUrl="Page2-1.aspx"/>

    <asp:MenuItem Text="Page 2-2" NavigateUrl="Page2-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem Text="Page 3" NavigateUrl="Page3.aspx">

    <asp:MenuItem Text="Page 3-1" NavigateUrl="Page3-1.aspx"/>

    <asp:MenuItem Text="Page 3-2" NavigateUrl="Page3-2.aspx"/>

  </asp:MenuItem>

  </Items>

</asp:Menu>

...

</html>

Listing 12-7. Code to style a Menu control.

Selected Styles and Master Pages

When an <asp:Menu> control appears on a master page, the "selected" styles (StaticSelectedStyle) do not work as expected. That is, menu styling to indicate a clicked link does not appear when the new content page is loaded. In the above example, selected items are displayed with a white background and bold characters. However, special scripting is needed to produce this effect. The need for this scripting is because selected styles are applied after the page loads. Since the new content page also causes reloading of the master page, prior reference to the selected menu item is no longer available. The new page "doesn't remember" which menu item was clicked on the previous page.

A script to style a selected menu item to correspond with a loaded page is shown below. This Page_Load subprogram appears on the example master page. It gets the path of the current page, extracts the .aspx file name from the path, and programmatically selects the menu item with a matching NavigateUrl property. Once this item is selected, all StaticSelectedStyle properties are automatically applied to the item.

Sub Page_Load

  '-- Get page name from relative path

  Dim ThisPage As String = Page.AppRelativeVirtualPath

  Dim SlashPos As Integer = InStrRev(ThisPage,"/")

  Dim PageName As String = Right(ThisPage, Len(ThisPage) - SlashPos)

  '-- Select menu item with matching NavigateUrl property

  Dim ParentMenu As MenuItem

  Dim ChildMenu As MenuItem

  For Each ParentMenu in NavigationMenu.Items

    If ParentMenu.NavigateUrl = PageName Then

      ParentMenu.Selected = True

    Else

      For Each ChildMenu in ParentMenu.ChildItems

        If ChildMenu.NavigateUrl = PageName Then

          ChildMenu.Selected = True

        End If

      Next

    End If

  Next

End Sub

Listing 12-8. Programmatically selecting a Menu item.

The relative path to a Web page is contained in that page's AppRelativeVirtualPath property. For instance, when content page Page1-1.aspx is loaded in the above example, the Page.AppRelativeVirtualPath property of this page resembles the following string,

"~/Tutorials/ASPNET2/ASPNET11/Site4/Page1-1.aspx"

giving the relative directory path to the current page. Of interest here is just the name of the page since this is the value of the NavigateUrl property of the menu item that was clicked to load this page.

This page name is extracted from the string by searching the string backwards with the Visual Basic InStrRev() method to locate the final "/" character, beyond which is the page name. Then the Visual Basic Right() method extracts this page name.

Dim ThisPage As String = Page.AppRelativeVirtualPath

Dim SlashPos As Integer = InStrRev(ThisPage,"/")

Dim PageName As String = Right(ThisPage, Len(ThisPage) - SlashPos)

Listing 12-9. Extracting a page name from a directory path.

Now it is a matter of iterating the items in the menu to locate the one which has a NavigateUrl property that matches this page name.

Dim ParentMenu As MenuItem

Dim ChildMenu As MenuItem

For Each ParentMenu in NavigationMenu.Items

  If ParentMenu.NavigateUrl = PageName Then

    ParentMenu.Selected = True

  Else

    For Each ChildMenu in ParentMenu.ChildItems

      If ChildMenu.NavigateUrl = PageName Then

        ChildMenu.Selected = True

      End If

    Next

  End If

Next

Listing 12-10. Iterating items in a Menu list.

A menu control has an Items collection of all root-level (first-level) menu items. If a menu item also has a submeum of items, these are contained in its ChildItems collection. A For Each...Next loop is used to iterate these collections. In the above example, the NavigationMenu.Items collection of root-level Items (ParentMenu) is iterated, within which these Items' collections of ChildItems (ParentMenu.ChildItems) are iterated. A test is made of each menu item to determine if has a NavigateUrl property value matching that of the page name extracted from the page path. If so, then this menu item is selected by setting its Selected="True" property. By doing so, StaticSelectedStyle settings are applied to this menu item, and the item is highlighted to match the displayed page.

PopOut Menus

When the number of StaticDisplayLevels is set to less than the number of menu levels, a PopOut submenu is displayed when the mouse is positioned over a static menu item. In the following example, StaticDisplayLevels="1" displays only the first (level-0) static menu items. Also, an arrowhead () appears next to the menu item to indicate the presence of a PopOut submenu.

Figure 12-10. Navigation menu with PopOut submenus.

PopOut submenus are styled with "dynamic," rather than "static," style settings as shown in the following <asp:Menu> code for the above example. In this case, the PopOut submenu is styled to match the static menu through its DynamicMenuStyle settings for the submenu block, its DynamicMenuItemStyle settings for individual menu items, and its DynamicHoverStyle settings for mouse-over events.

<asp:Menu id="NavigationMenu" Runat="Server"

  StaticDisplayLevels="1"

  StaticMenuItemStyle-VerticalPadding="2"

  StaticMenuItemStyle-Font-Name="Verdana"

  StaticMenuItemStyle-Font-Size="9pt"

  StaticMenuItemStyle-ForeColor="#990000"

  StaticHoverStyle-BackColor="#707070"

  StaticHoverStyle-ForeColor="#FFFFFF"

  DynamicMenuStyle-HorizontalPadding="5"

  DynamicMenuStyle-VerticalPadding="2"

  DynamicMenuStyle-BackColor="#E0E0E0"

  DynamicMenuStyle-ForeColor="#990000"

  DynamicMenuStyle-BorderWidth="1"

  DynamicMenuStyle-BorderColor="#C0C0C0"

  DynamicMenuItemStyle-VerticalPadding="2"

  DynamicMenuItemStyle-Font-Name="Verdana"

  DynamicMenuItemStyle-Font-Size="9pt"

  DynamicMenuItemStyle-ForeColor="#990000"

  DynamicHoverStyle-BackColor="#707070"

  DynamicHoverStyle-ForeColor="#FFFFFF"

> 

  <Items>

  <asp:MenuItem Text="Page 1" NavigateUrl="Page1.aspx">

    <asp:MenuItem Text="Page 1-1" NavigateUrl="Page1-1.aspx"/>

    <asp:MenuItem Text="Page 1-2" NavigateUrl="Page1-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem Text="Page 2" NavigateUrl="Page2.aspx">

    <asp:MenuItem Text="Page 2-1" NavigateUrl="Page2-1.aspx"/>

    <asp:MenuItem Text="Page 2-2" NavigateUrl="Page2-2.aspx"/>

  </asp:MenuItem>

  <asp:MenuItem Text="Page 3" NavigateUrl="Page3.aspx">

    <asp:MenuItem Text="Page 3-1" NavigateUrl="Page3-1.aspx"/>

    <asp:MenuItem Text="Page 3-2" NavigateUrl="Page3-2.aspx">

      <asp:MenuItem Text="Page 3-2-1" NavigateUrl="Page3-2-1.aspx"/>

      <asp:MenuItem Text="Page 3-2-2" NavigateUrl="Page3-2-2.aspx"/>

    </asp:MenuItem>

  </asp:MenuItem>

  </Items>

</asp:Menu>

Listing 12-11. Creating a Menu control with PopOut submenus.

The PopOut arrowhead can be suppressed on the static menu by setting StaticEnableDefaultPopOutImage to False (or DynamicEnableDefaultPopOutImage to False for a submenu), or the arrowhead can be replaced with a graphic image by coding StaticPopOutImageUrl (or DynamicPopOutImageUrl for a submenu), and providing a URL to the image.

If the PopOut menu itself has additional levels of submenus, then the same dynamic configuration and style settings are applied to any additional levels. This formatting is shown by the three levels of menu items under "Page 3" in the above example. Also, special styling for selected menu items is not applied since only the first-level items would be so styled.

Scrolling PopOut Menus

If the length of a list of menu items does not fit on the page, then the items are presented as a scrolling list. In Figure 12-11, the list of items under the "Page 1" menu displays with scrolling. (The additional items do not link to actual pages.)

Figure 12-11. A scrolling PopOut menu.

You can change the graphic images appearing at the top and bottom of a scrolling menu list by supplying their URLs in the Menu control's ScrollDownImageUrl and ScrollUpImageUrl properties. Alternate text displayed on a mouse-over of these images are given in the ScrollDownText and ScrollUpText properties.

Graphic PopOut Menus

Graphic images can be used in place of text for PopOut menus. This effect is shown below with coding of the <asp:Menu> control identical to the previous example, with ImageUrl properties replacing Text properties in the <asp:MenuItem> controls.

Figure 12-12. PopOut menus with graphic links.