ASP.NET Menu Control - Defining the Structure

APNSoft Menu uses XML for defining the structure since XML is the most convenient and widespread format for structured data. The XML Structure consists of elements (items and separators):

<Menu>
    <item title="Main Page" />
    <separator />
    <item title="About Us" />
    <item title="Products">
        <item title="Menu" />
        <item title="DataGrid" />
        <item title="TreeView" />
    </item>
    <item title="Contacts" />
</Menu>

The code above creates the following menu (horizontal orientation):

Structure elements:

<Menu /> - the root element for entire Menu Structure File. Does not include attributes.
<item /> - one item element. Each item element can include other elements. Available attributes:
- AutoPostBackOnItemClick - specifies a value indicating whether the control causes a postback to the server when the item is clicked.
- ClientSideOnItemClick - specifies the client-side code to be launched when the item is clicked. Can include variables $ComponentID$, $ItemID$ and $Title$. Each variable is replaced to the corresponding value.
- CSS_ItemHoveredTD - specifies the name of the CSS class used for precise item customization. It is applied to the hovered item TD.
- CSS_ItemSelectedTD - specifies the name of the CSS class used for precise item customization. It is applied to the selected item TD.
- CSS_ItemTD - specifies the name of the CSS class used for precise item customization. It is applied to the item TD.
- CSS_SubMenuDIV - specifies the name of the CSS class used for precise submenu customization. It is applied to the submenu DIV.
- href, target - the URL and target the browser is directed to when a user clicks the Item. The href attribute can include variables $ComponentID$, $ItemID$ and $Rnd$. Each variable is replaced to the corresponding value. The $Rnd$ displays a random number. It can be used as an additional parameter to avoid page caching in browser.
- icon - specifies the name of item's icon image. The icon image displayed at the left side of the item. The icon images must be located in the Skin Folder as specified by the SkinFolder property.
- iconOver - specifies the name of icon for hovered item.
- iconWidth, iconHeight - one Item's icon image width and height. Attributes are optional. Control automatically calculates Width and Height of each icon.
- id - specifies a unique identifier for the element. The attribute is required. If the id attribute is not specified, the component will automatically set it for each item (id="itm1", id="itm2", etc.).
- image - specifies the name of the picture, used as one menu item. This attribute is used instead of the title attribute. The image file must be located in the Skin Folder as specified by the SkinFolder property.
- imageOver - specifies the name of the picture, used for hovered item.
- imageWidth, imageHeight - one Item's image width and height. Attributes are optional. Control automatically calculates Width and Height of each image.
- SubMenuMarginLeft, SubMenuMarginTop - the width of the left (top) margin of the submenu. Use these attributes to specify the position of every single submenu.
- Template - specifies the path to item's template file.
- title - specifies the text (caption) displayed for the item. Can include HTML formatting by using of square brackets ("[" and "]") instead of standard corner brackets ("<" and ">"). Double square brackets ("[[" and "]]") are used to show single square brackets.
- roles - specifies the collection of comma-separated user roles that are associated with the element. User roles provide developers with an easy and flexible way to control access to menu elements.
- selected - specifies a value indicating whether the item is selected.
- tooltip - specifies the text for item's tooltip.

<separator /> - element for horizontal or vertical separator. Available attributes:
- CSS_SeparatorTD - specifies the name of the CSS class used for precise separator customization. It is applied to the separator TD.
- id - specifies a unique identifier for the element. The attribute is required. If the id attribute is not specified, the component will automatically set it for each separator (id="spr1", id="spr2", etc.).
- image - specifies the name of the picture, used for separator.
- imageWidth, imageHeight - one separator's image width and height.
- roles - specifies the collection of comma-separated user roles that are associated with the element.

Menu element examples:

<item id="i1" title="Home" />
<item id="i1" title="Home" href="~/Default.aspx?ItemID=$ItemID$&amp;Rnd=$Rnd$" />
<item title="Google" href="http://www.google.com" target="_blank" />
<item title="JavaScript" ClientSideOnItemClick="alert('The $Title$ ($ItemID$) is clicked!');" />
<item title="New" icon="IconNew.gif" iconOver="IconNewActive.gif" roles="Admins, Owners" />
<item title="TV Schedule" Template="~/Templates/Template.ascx" />
<item image="Home.jpg" imageOver="HomeActive.jpg" />
<separator image="SeparatorVertical.jpg" />

Attention! Element names and attributes are case-sensitive. Be careful when you're typing in your data.

Applying the XML Structure or Data Source:

You can save the XML definition structure as a file and bind the menu by specifying the StructureFileURL property. APNSoft Menu has support to use the Web.sitemap file as a standard menu structure.

<APNSoft:APNSoftMenu id="myMenu" runat="server"
    StructureFileURL = "~/Structures/Menu.xml" />

You can also apply the XML Document with structure by using the DataSource property. If the menu loads structure from the database, you should set the DataSource property to specify a source of data and call the DataBind() method. To create an appropriate table in the SQL Server, use the following SQL command:

CREATE TABLE [dbo].[Items](
    [id] [nvarchar](20) NOT NULL,
    [pid] [nvarchar](20) NULL,
    [Type] [nvarchar](10) NOT NULL CONSTRAINT [DF_Items_Type] DEFAULT ('item'),
    [title] [nvarchar](250) NULL,
    [href] [nvarchar](250) NULL,
    [target] [nvarchar](100) NULL,
    [tooltip] [nvarchar](250) NULL,
    [icon] [nvarchar](100) NULL,
    [iconOver] [nvarchar](100) NULL,
    [iconWidth] [tinyint] NULL,
    [iconHeight] [tinyint] NULL,
    [image] [nvarchar](100) NULL,
    [imageOver] [nvarchar](100) NULL,
    [imageWidth] [tinyint] NULL,
    [imageHeight] [tinyint] NULL,
    [AutoPostBackOnItemClick] [bit] 
        NOT NULL CONSTRAINT [DF_Items_AutoPostBackOnItemClick] DEFAULT ((0)),
    [ClientSideOnItemClick] [nvarchar](250) NULL,
    [selected] [bit] NOT NULL CONSTRAINT [DF_Items_selected] DEFAULT ((0)),
    [CSS_ItemTD] [nvarchar](100) NULL,
    [CSS_ItemHoveredTD] [nvarchar](100) NULL,
    [CSS_ItemSelectedTD] [nvarchar](100) NULL,
    [CSS_SubMenuDIV] [nvarchar](100) NULL,
    [CSS_SeparatorTD] [nvarchar](100) NULL,
    [roles] [nvarchar](50) NULL,
    [Template] [nvarchar](255) NULL
)

You can also build up menu at runtime. APNSoft Menu provides an extremely rich and powerful server-side API allowing developer to add, remove or edit menu elements and element collections. You can programmatically control any item at runtime by using two classes MenuElement and MenuElementCollection.