CMS.skmMenuControl
MenuItemCollection represents a collection of instances.
Each item in a menu is represented by an instance of the class.
The MenuItem class has a SubItems property, which is of type MenuItemCollection. This
MenuItemCollection, then, allows for each MenuItem to have a submenu of MenuItems.This flexible
object model allows for an unlimited number of submenu depths.
Adds a MenuItem to the collection. If the ViewState is being tracked, the
MenuItem's TrackViewState() method is called and the item is set to dirty, so
that we don't lose any settings made prior to the Add() call.
The MenuItem to add to the collection
The ordinal position of the added item.
Adds a spacer to the collection.
The height of the spacer to add to the collection
The ordinal position of the added item.
Adds a spacer to the collection.
The height of the spacer to add to the collection
The CssClass for the spacer to add to the collection
The ordinal position of the added item.
Adds a spacer to the collection.
The height of the spacer to add to the collection
The CssClass for the spacer to add to the collection
/// The Text for the spacer to add to the collection
The ordinal position of the added item.
Adds a header to the collection.
The text for the header to add to the collection
The ordinal position of the added item.
Adds the MenuItems in a MenuItemCollection.
The MenuItemCollection instance whose MenuItems to add.
Clears out the entire MenuItemCollection.
Determines if a particular MenuItem exists within the collection.
The MenuItem instance to check for.
A Boolean - true if the MenuItem is in the collection, false otherwise.
Returns the ordinal index of a MenuItem, if it exists; if the item does not exist,
-1 is returned.
The MenuItem to search for.
The ordinal position of the item in the collection.
Inserts a MenuItem instance at a particular location in the collection.
The ordinal location to insert the item.
The MenuItem to insert.
Removes a specified MenuItem from the collection.
The MenuItem instance to remove.
Removes a MenuItem from a particular ordinal position in the collection.
The ordinal position of the MenuItem to remove.
Copies the contents of the MenuItem to an array.
Gets an Enumerator for enumerating through the collection.
Indicates that changes to the view state should be tracked. Calls TrackViewState()
for each MenuItem in the collection.
Saves the view state in an object array. Each item in the collection has its
SaveViewState() method called. This array is then returned, representing the
state of the MenuItemCollection.
An object array.
Iterate through the object array passed in. For each element in the object array
passed-in, a new MenuItem instance is created, added to the collection, and populated
by calling LoadViewState().
The object array returned by the SaveViewState() method in
the previous page visit.
Returns the number of elements in the MenuItemCollection.
The actual number of elements contained in the .
Gets a value indicating whether access to the is synchronized (thread-safe).
Gets an object that can be used to synchrnoize access to the .
Gets the at a specified ordinal index.
Allows read-only access to the 's elements by index.
For example, myMenuCollection[4] would return the fifth instance.
Gets the MenuItem with a specified Name.
The MenuItem class has a Name property that allows for items
to be indexed by name. For example, myMenuCollection["Contact"] would return the
instance with the Name "Contact", or null if no such
MenuItem existed in the MenuItemCollection.
A required property since MenuItemCollection implements IStateManager. This
property simply indicates if the MenuItemCollection is tracking its view state or not.
A MenuItem represents a single item in a menu.
A MenuItem is a single "item" in a menu. Typically a MenuItem will have some
associated with it, and often a or . MenuItems can also optionally
have a set of , which represents a nested submenu.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
Creates a new MenuItem instance.
This method saves the state for a particular menuitem.
This method returns a Triplet, where the first item is the result from the MenuItem's ViewState's
SaveViewState() method call. The second is the ViewState saved from the
subItems MenuItemCollection instance. The third item is the ViewState saved from the
RolesCollection.
A Triplet containing the ViewState and state of the subitems.
Loads the state upon postback back into the MenuItem.
The state preserved from the SaveViewState() method in the
previous page invocation.
Starts tracking view state for the ViewState and subItems properties.
Gets or sets a value indicating whether the Web server control is enabled.
true if the control is enabled, false otherwise; the default is true.
Gets or sets the background color of the Web server control.
Use the BackColor property to specify the background color of the Web server control.
Gets or sets the border color of the Web control.
A System.Drawing.Color that represents the border color of the control. The default is Color.Empty, which indicates that this property is not set.
Use the BorderColor property to specify the border color of the Web Server control.
Gets or sets the border style of the Web server control.
One of the BorderStyle enumeration values. The default is NotSet.
Use the BorderStyle property to specify the border style for the Web server control. This property is set using one of the BorderStyle enumeration values.
Gets or sets the border width of the Web server control.
A Unit that represents the border width of a Web server control. The default value is Unit.Empty, which indicates that this property is not set.
Use the BorderWidth property to specify a border width for a control.
Gets or sets the Cascading Style Sheet (CSS) class rendered by the Web server control on the client.
Gets the font properties associated with the Web server control.
A FontInfo that represents the font properties of the Web server control.
Gets or sets the foreground color (typically the color of the text) of the Web server control.
Gets or sets the height of the Web server control.
Gets or sets the text displayed when the mouse pointer hovers over the Web server control.
Gets or sets the width of the Web server control.
Specifies if the MenuItem is tracking ViewState. Required, since MenuItem
implements the IStateManager interface.
Gets or sets the MenuItem's image.
If both of the MenuItem's and properties are specified,
will be used.
Menu ALT tag
Gets or sets the alternate text for the MenuItem's image.
This value, if specified, is rendered as the alt attribute in the generated
<img> element.
Gets or sets an image to be shown to the right of the menuitem's text or main image.
You can only have either a or a . If both
are specified, only the will be used.
Gets or sets the width of the space to show an image in on the right of the MenuItem's or
main image.
The default value is Unit.Empty.
Specifies alignment for an image to be shown to the right of the MenuItem's or main image.
Set to one of the values of the System.Web.UI.WebControls.ImageAlign enumeration.
The default is ImageAlign.NotSet
Unique class id
Browser
OverStyle
Set Left over image
Set right over image
Gets or sets an image to be shown to the left of the MenuItem's or main image.
You can only have either a or a . If both are
specified, only the will be used.
Gets or sets the width of the space to show an image in on the left of the MenuItem's or main image.
The default value is Unit.Empty.
Specifies alignment for an image to be shown to the left of the MenuItem's or main image.
Set to one of the values of the System.Web.UI.WebControls.ImageAlign enumeration.
The default is ImageAlign.NotSet
Gets or sets the MenuItem's mouseover image.
The client-side mouseover event fires when the user's mouse moves over the MenuItem.
Gets or sets the MenuItem's mouseup image.
Gets or sets the MenuItem's mousedown image.
The client-side mousedown event fires when the mouse is over the MenuItem
and the uses clicks the mouse button.
Gets or sets the MenuItem's name.
A string value denoting the MenuItem's Name. The default is an empty string.
Use the Name property to give a unique, identifying name to a MenuItem instance.
The class, which contains a collection of MenuItem instances, can
be searched for a MenuItem with a specified Name.
Gets or sets the MenuItem's text content.
For total customization of the appearance of the MenuItem, the Text property can have
HTML content.
The following example illustrates using HTML content in the Text property:[C#]
MenuItem mi = new MenuItem();
mi.Text = "<b>This will be bold!</b>";
Gets or sets the MenuItem's Url.
If a MenuItem has a Url value, the MenuItem is "clickable." That is, the end user
will be able to click the MenuItem and be whisked to the specified URL.The Url value can use
the ~ notation. For this to work, though, the Menu class's DefaultResolveUrl property must be
set to True.
Specifies the URL the user will be whisked to when the MenuItem is clicked. The default value
is String.Empty. The Url property is optional.
Gets or sets the MenuItem's Javascript command.
Gets or sets the MenuItem's target used when the is navigated to.
The property must be set to a non-empty string for Target to have any affect.
To have a MenuItem opened in a new window, set Target to _blank
Retrieves the MenuItem's set of SubItems.
The SubItems collection is useful when programmatically creating or modifying
a menu's content.
Specifies the MenuItem's roles.
Gets or sets the MenuItem's ID. It is not recommended that this be set directly.
The ID for each MenuItem is programmatically set in the class's
method.
Gets or sets the MenuItem's type. It is not recommended that this be set directly.
The MenuItem type can be one of the available enumeration values.
The default is MenuItemType.MenuItem.
Gets or Sets the CommandName property.
If a MenuItem's CommandName property is set, and the property is
not set, then the MenuItem, when clicked, will cause the Web Form to postback, and a
MenuItemClicked event will be raised.
Gets or sets the MenuItem's mouseover CSS class.
Gets or sets the MenuItem's mouseup CSS class.
Gets or sets the MenuItem's mousedown CSS class.
Specifies whether URL should be resolved before being output.
If either in the class is true or this value is true,
then the URL for the menuitem will be resolved.
Specifies horizontal alignment for the MenuItem.
One of the horizontal alignment options from the System.Web.UI.WebControls.HorizontalAlign enumeration.
The default is HorizontalAlign.NotSet.
The horizontal alignment indicates how the text and/or images of the MenuItem are aligned.
Specifies vertical alignment for the MenuItem.
One of the vertical alignment options from the System.Web.UI.WebControls.VerticalAlign enumeration.
The default is VerticalAlign.NotSet.
Provides the EventArgs class for the MenuItemClick event.
This EventArgs provides a single string parameter: CommandName
Describes which menuitem was clicked by returning the command name property.
Readonly access to commandName parameter of EventArgs class
Represents the method that will handle the class's
event.
The source of the event.
A that contains the event data.
The menu class is an ASP.NET server control that displays a client-side menu utilizing
CSS and DHTML. Its contents are bound through an XML file or by programmatically constructing the
Menu's menu items. For full documentation, FAQs, examples, and a messageboard, be sure to check out the
official skmMenu site: skmMenu.com.
Raises the event. This allows you to provide a custom handler for the event.
Instance of that contains the event data.
SaveViewState saves the state of the menu into an object (specifically, an object array
with five indices). This is required to have the state persisted across postbacks.
A five-element object array representing the menu's state.
Loads the state from the passed in saveState object. This method runs during the
page life-cycle, and is required for the menu to work across postbacks.
The state persisted by SaveViewState() in the previous life-cycle.
TrackViewState informs all of the menus complex properties that they, too, need to
track their viewstate changes.
The Render method is responsible for generating the HTML markup.
HTMLTextWriter instance to write to.
Render ensures that the Menu is created in a server-side Web Form. This check is required
because the Menu may contain instances that, when clicked, cause a postback.
This method is called from base.Render(), and starts the build menu process.
Event handler for the DataBinding event.
This method runs when the DataBind() method is called. Essentially, it clears out the
current state and builds up the menu from the specified .
Generates the client-side JavaScript.
For non-databound (dynamic) menus, OnPreRender also sets all of the MenuIDs.
For more information on adding client-side script via an ASP.NET server control, refer to:
Injecting Client-Side Script from an ASP.NET Server Control
Determines what images are used by a specified instance.
The MenuItem to examine.
The class has a number of image properties, like MouseOverImage,
MouseDownImage and others. This method checks these properties to determine if any images
are used. If it locates any, it marks the image to be preloaded using client-side JavaScript.
Creates a MenuID for a MenuItem.
The MenuItem that will have its MenuID set.
The MenuID of the MenuItem mi's parent.
If MenuItem mi has a parent, the indexValue indicates
what index mi is in its parent's set of MenuItem children.
BuildMenuID() formats the index as a three-digit number. This puts an upperbound on the
number of MenuItems any menu can contain. Precisely, no single menu may contain more than 1,000
MenuItems.
Allows for two strings to be passed in - a default CSS class and a specific Menu class. If no
Menu class is specifies, the default class is returned.
Allows for three strings to be passed in - a default CSS class, a specific Menu class, and a style class.
The proper class string is returned.
This method utilizes ResolveUrl() if needed. ResolveUrl() resolves any tildes that may
appear in the URL into the proper path. For more information see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwebuicontrolclassresolveurltopic.asp
BuildMenu builds the top-level menu. It is called from the OnDataBinding method as well
as from . It has code to check if the top-level menu should be
laid out horizontally or vertically.
AddMenu is called recusively, doing a depth-first traversal of the menu hierarchy and building
up the HTML elements from the object model.
The ID of the parent menu.
The collection of menuitems.
Determines if a user belongs to a role for a particular .
The MenuItem to check.
true if the user has the right permissions to view this MenuItem; false otherwise.
UserHasPermission() works by returning true if there are no roles defined for mi
or if there is at least one role defined for the user and the mi role collection and user role collection
are not disjoint.
For Internet Explorer 5.5 and up, IFRAMEs are used. This method returns the client-side JavaScript to show/hide
the IFRAME.
A string vaue containing either the string true or false. A value of
true makes the IFRAME visible; false hides it.
The client-side id of the IFRAME.
A client-side JavaScript function call that will show/hide the IFRAME.
This method is used from the OnDataBinding method; it traverses the XML document,
building up the object model.
The current menuItem XmlNode
The ID of the parent menuItem XmlNode
A set of MenuItems for this menu.
This method creates a single and is called repeatedly from .
The MenuItem XmlNode.
The parent MenuItem's ID.
The ordinal index of the MenuItem in the set of MenuItems.
A new instance.
Creates a MenuItem spacer.
Registers the main client script.
RegisterClientScriptBlock() adds the global variables and JavaScript methods. Depending on
how skmMenu is configured, this client-side script is either emitted directly to the browser in the
HTML stream, or references an external JavaScript file. It is recommended that the external JavaScript
file approach be used, since it yields better performance on both the client and server.
For more information on using an external JavaScript file, see the property.
Registers the startup client script.
The startup script involves calls to the client-side skm_registerMenu() function.
Registers the SubMenus for the menu with a JavaScript array.
A client-side array skm_subMenuIDs maintains an array of all of the id values
of the client-side submenus. This is useful in dynamically determining the client position of a submenu.
Registers the Preload command to preload any images.
Preloading images used in a page improves the user experience by loading an image before it is needed.
If a menu has rollover images and does not preload its images, there will be a short delay when the
user mouses over the menu item for the first time, as the image must then be downloaded. Preloading the images
removes this delay since the image will have likely been downloaded by the time the user mouses over the menu
image.For more information on preloading JavaScript images refer to this article.
Returns the javascript that instantiates a style info object
that corresponds to the style specified.
Double conversion function to avoid errors on IE 7
Returns the menu layout based on the given string
String layout representation
Script control ID (ID used for the script functions)
Occurs when a associated with a command is clicked.
A helper method that determines if an external script is being used.
UseExternalScript simply returns the result of the check ExternalScriptUrl != null.
Return the configured URL for the external script.
The external JavaScript file maybe specified either in the Web.config file or through the
Menu control's property. ExternalScriptUrl checks first the Web.config
file and then the property to determine if an external JavaScript file should be used.
Sets or gets the name of the XML file or XmlDocument object that is the datasource for the menu.
The DataSource can be assigned either a string filename to an XML file, or an
XmlDocument object. Attempting to assign the DataSource to something other than a string or
XmlDocument will result in an ArgumentException being thrown.
Returns the Menu's top-level s.
This returns a instance holding the top-level menu items only.
If you want to drill down into submenu items, you must programmatically recurse down. For example,
imagine we had a menu with two top-level menu items, File and Help, and File had three menu items,
New, Open, and Save. To programmatically access the New menu item from the Menu you'd use:
MenuItem FileNewMenuItem = MenuControlID.Items[0].Items[0];
Specifies the roles the current user belongs to. When assigning roles to the MenuItems, the user's roles
affect what menu items are displayed.
Each MenuItem in a skmMenu can be assigned a set of roles. A role is a name that implies some
level of access. Roles are denoted as strings. Example roles might be: developer, tester, and admin.
To denote a role for a , the property can be used programmatically,
or the <roles> XML element can be used if the menu data is supplied in an XML file. (For more
information on the <roles> XML element and binding menu data via an XML file, consult
http://skmmenu.com/menu/Download/XMLStructure.html.
The Menu class's UserRoles property specifies the set of roles the user viewing the page has. This
needs to be set programmatically in the first page load (the role information is persisted across postbacks).
Typically this role assignment will need to be done by looking up the current user's set of roles in a database
or some other ACL store.
After the UserRoles property has been set, you can bind the XML data to skmMenu through a call to
DataBind. Only those s that either (a) have no roles defined or (b) has a role
collection that intersects the UserRoles role collection, will be rendered. For a live demo of
roles with skmMenu, see http://skmmenu.com/menu/Examples/Roles.aspx.
Specifies the style for selected s.
A MenuItem is selected when the user moves the mouse over the menu item.
Specifies whether URL's should be resolved before being output.
If this property is marked True then MenuItem URLs can use ~, as in ~/SomeDir/SomePage.htm. Internally, if this
property is set to True the ResolveUrl() method is used.
Specifies whether the top level menu should remain highlighted when the submenu beneath is displayed.
Specifies whether a submenu is displayed on mouse over or when clicked.
A value of True indicates that submenus are displayed with a menu item is clicked;
a value of False indicates that the submenu is displayed when the menu item is moused over.
Gets or sets the z-index style value for the menu.
For Internet Explorer, submenus are displayed using IFRAMEs. Using IFRAMEs keeps the menu
above other form elements, such as drop-down lists. The zIndex specifies the "height" of the IFRAME
relative to othjer elements on the page. The default value of 1000 should ensure that the menus are
always the top-most elements on the page.
Gets or sets the opacity style value for the menu.
Opacity values must be between 0 and 100.
The opacity property only works for select Web browsers: IE 5.0+, Netscape 6+ and Mozilla.
Gets or sets the value for css class used for SubMenus.
If SubMenuCssClass is not specified and CssClass is specified, CssClass is
used instead.
If is true, menu will open submenus to the other side.
Gets or sets the default CSS class name for the 's CSS class.
If a has no specified CSS class, the DefaultCssClass is used instead.
Gets or sets the default value for the menuitem's mouse over css class. Used when a menuitem has no value specified.
Gets or sets the default value for the menuitem's mouse down css class. Used when a menuitem has no value specified.
Gets or sets the default value for the menuitem's mouse up css class. Used when a menuitem has no value specified.
Gets or sets the path to an external JavaScript file. If no external path is specified, the JavaScript is
rendered by the control directly in the page.
It is highly recommended that you utilize an external JavaScript file, as it promises performance increases
both for the client and server. The client can cache an external JavaScript file, thereby reducing the bandwidth
needed to be downloaded. On the server side, using an external JavaScript file results in several dozen lines
of JavaScript code not needing to be rendered.To use an external JavaScript file, place the skmMenu.js file
that was included in the download in a directory in your Web site. You can then set this property to the
path of the skmMenu.js file.
[C#] This example assumes that the skmMenu.js file was placed in the /scripts/ directory of your Web site.
protected Menu myMenuControl;
private void Page_Load(object sender, EventArgs e)
{
myMenuControl.ScriptPath = "/scripts/skmMenu.js";
...
}
Gets or sets the default target for links in menuitems. Used if no target property is specified for a menuitem.
Gets or sets padding for each menuitem (pixels).
Menus and submenus are rendered as HTML tables. This property, then, specifies the rendered
table's CellPadding.
Gets or sets the spacing for each menuitem (pixels).
Menus and submenus are rendered as HTML tables. This property, then, specifies the rendered
table's CellSpacing.
Specifies the style for unselected s.
An unselected MenuItem is one that does not have the mouse cursor hovering over it.
Sets or Gets the menu's layout direction.
A enumeration value. The default is Vertical
Sets or Gets the menu's mouse cursor.
A enumeration value. The default is MouseCursor.Default.
Setting the Cursor property to MouseCursor.Pointer will have the browser display
a mouse pointer when the mouse is above a clickable menu item.
Sets or Gets the menu's gridline property.
This property is set with one of the GridLines enumeration values. The default is None.
Menus and submenus are rendered as HTML tables. This property, then, specifies the rendered
table's GridLines property value.
The following table lists the possible values:
ValueDescription
- NoneNo cell border is displayed.
- HorizontalOnly the upper and lower borders of the cells in a data listing control are displayed.
- VerticalOnly the left and right borders of the cells in the data list control are displayed.
- BothAll borders of the cells in a data listing control are displayed.
Gets or sets the number of half seconds to display the menu after the user's mouse
has left the menu, before hiding the menu.
The number of half-seconds to delay after the user's mouse has left the menu before hiding the menu. Must have an integer value greater than
or equal to 0. The default is 2, causing the submenus to delay for one second before vanishing.
It is recommended that this property have at least a value of 1. Setting it to 0 will cause the
submenu to disappear immediately after the user's mouse cursor leaves the submenu area. This can
result in a frustrating user experience.
Specifies what SRC property should be loaded into an IFRAME.
When the user is using Internet Explorer to render a page with skmMenu on it, the skmMenu submenus
are rendered as IFRAMEs. By default, the SRC is a blank string. If you are using skmMenu on SSL, however, this
blank SCR will cause a dialog box to appear warning the user that both secure and non-secure items are
being displayed. To circumvent this, you need to create a blank page, like blank.html. Configure this
property so that the SCR of the IFRAME is then blank.html. This is only needed when using skmMenu over
SSL.
Indicates if the last selected item should be highlighted even if mouse is moved out.
When HighlightLastSelectedItem is true, this property contains index of menu item that will be highlighted by default.
Indicates if z-index values should be rendered in the style attributes.
Provides a collection of roles.
Indicates that changes to the view state should be tracked.
Returns an array of objects, where each object is a string in the collection.
An object array.
Iterate through the object array passed in. For each element in the object array
passed-in, a new role is added to the collection.
The object array returned by the SaveViewState() method in
the previous page visit.
Adds a new role to the collection.
The name of the role to add.
Adds a range of roles to the collection.
A string array of roles to add.
Removes a role from the collection.
The name of the role to remove.
Clears out the roles collection.
Returns a Boolean indicating if the passed-in role name exists in the role collection.
A role.
Returns true if role is contained in the collection, false if it is not.
Returns true if this role collection and the passed in role collection are disjoint (share no elements in
common).
A role collection.
true if the collections are disjoint, false otherwise.
Returns the number of roles in the collection.
An integer value greater than or equal to zero indicating the number of roles in the role collection.
Returns the list of roles as a string array.
The RoleCollection class only contains methods to add, remove, and check to see if a role exists in
the collection. It does not provide a means to enumerate through the roles. In order to enumerate through
the roles, use this property to retrieve the roles as a string array.
Specifies if the RoleCollection is tracking ViewState. Required, since RoleCollection
implements the IStateManager interface.
Designer class for the menu control.
Constructor.
Initialization.
Returns design-time HTML.
Specifies the type of .
A standard menu item.
A separator menu item. Separators provide a level of separation between menu items.
A menu item header.
Specifies the visual orientation for the 's top-level menu items.
The main menu in Windows applications use the Horizontal approach: for example, the File menu is
laid next to the Edit menu which is laid next to the View menu, and so on. Many Web pages, however, use
a Vertical layout, displaying the top-level menu items along the left hand side of the Web page.
Each top-level menu item is laid out end-to-end.
Each top-level menu item is laid one above the other.
The MouseCursor enumeration specifies the different cursors for the menu.
The Pointer option will only display a pointer cursor for clickable menu items.
Default pointer or pointer controlled by CSS.
Pointer normally associated with links (usually a hand).
The MenuPositioning enumeration specifies whether absolute or relative positioning will be used.
Absolute positioning.
Relative positioning.