System.Web 2.0.0.0 System.Web.UI.WebControls.CompositeControl System.ComponentModel.Designer("System.Web.UI.Design.WebControls.SiteMapPathDesigner, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.ComponentModel.Design.IDesigner") In this topic: Introduction Nodes Node Appearance Events Customizing the SiteMapPath Control Accessibility Declarative Syntax

Introduction

The control is a site navigation control that reflects data provided by the object. It provides a space-saving way to easily navigate a site and serves as a point of reference for where the currently displayed page is within a site. This type of control is commonly called a breadcrumb, or eyebrow, because it displays a hierarchical path of hyperlinked page names that provides an escape up the hierarchy of pages from the current location. . The is useful for sites that have deep hierarchical page structures, but where a or might require too much space on a page. The control works directly with your Web site's site map data. If you use it on a page that is not represented in your site map, it will not be displayed. For more information about site maps, see ASP.NET Site Navigation.

Nodes

The is made up of nodes. Each element in the path is called a node and is represented by a object. The node that anchors the path and represents the base of the hierarchical tree is called the root node. The node that represents the currently displayed page is the current node. Any other node between the current node and root node is a parent node. The following table describes the three different node types. Node type Description root A node that anchors a hierarchical set of nodes. parent A node that has one or more child nodes, but is not the current node. current A node that represents the currently displayed page.

Node Appearance

Each node displayed by a is a or control that you can apply a template or style to. The templates and styles are applied to nodes according to two rules of precedence: If a template is defined for a node, it overrides any style defined for the node. Templates and styles that are specific to types of nodes override general templates and styles defined for all nodes. The and properties are applied to all nodes, regardless of their node type. If both these properties are defined, the takes precedence. The and properties are applied to nodes that represent the currently displayed page. If a is defined in addition to the , it is ignored. If a is defined in addition to the , it is merged with the to create a merged style. This merged style uses all the elements of the , plus any additional elements of the that do not conflict with the . The and properties are applied to the node that represents the root of the site navigation hierarchy. If a is defined in addition to the , it is ignored. If a is defined in addition to the , it is merged with the to create a merged style. This merged style uses all the elements of the , plus any additional elements of the that did not conflict with the . Finally, if the currently displayed page is the root page of the site, the and are used instead of the or . The control uses the site map provider identified by the property as its data source for site navigation information. If no provider is specified, it uses the default provider for the site, identified in the property. Typically, this is an instance of the default site map provider for ASP.NET, the . If the control is used within a site but no site map provider is configured, the control throws an exception.

Events

The control also provides events that you can program against. This allows you to run a custom routine whenever an event occurs. The following table lists the events supported by the control. Event Description Occurs when the control first creates a and associates it with a . Occurs when a is bound to site map data contained by the .

Customizing the SiteMapPath Control

Classes that derive from override the method to customize the controls contained by the navigation control. For complete control over the way objects are created and added to the , derived classes override the method.

Accessibility

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.

Declarative Syntax

<asp:SiteMapPath
    AccessKey="string"
    BackColor="color name|#dddddd"
    BorderColor="color name|#dddddd"
    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|
        Inset|Outset"
    BorderWidth="size"
    CssClass="string"
    Enabled="True|False"
    EnableTheming="True|False"
    EnableViewState="True|False"
    Font-Bold="True|False"
    Font-Italic="True|False"
    Font-Names="string"
    Font-Overline="True|False"
    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|
        Large|X-Large|XX-Large"
    Font-Strikeout="True|False"
    Font-Underline="True|False"
    ForeColor="color name|#dddddd"
    Height="size"
    ID="string"
    OnDataBinding="DataBinding event handler"
    OnDisposed="Disposed event handler"
    OnInit="Init event handler"
    OnItemCreated="ItemCreated event handler"
    OnItemDataBound="ItemDataBound event handler"
    OnLoad="Load event handler"
    OnPreRender="PreRender event handler"
    OnUnload="Unload event handler"
    ParentLevelsDisplayed="integer"
    PathDirection="RootToCurrent|CurrentToRoot"
    PathSeparator="string"
    RenderCurrentNodeAsLink="True|False"
    runat="server"
    ShowToolTips="True|False"
    SiteMapProvider="string"
    SkinID="string"
    SkipLinkText="string"
    Style="string"
    TabIndex="integer"
    ToolTip="string"
    Visible="True|False"
    Width="size"
>
        <CurrentNodeStyle />
        <CurrentNodeTemplate>
            <!-- child controls -->
        </CurrentNodeTemplate>
        <NodeStyle />
        <NodeTemplate>
            <!-- child controls -->
        </NodeTemplate>
        <PathSeparatorStyle />
        <PathSeparatorTemplate>
            <!-- child controls -->
        </PathSeparatorTemplate>
        <RootNodeStyle />
        <RootNodeTemplate>
            <!-- child controls -->
        </RootNodeTemplate>
</asp:SiteMapPath>

Displays a set of text or image hyperlinks that enable users to more easily navigate a Web site, while taking a minimal amount of page space.

Constructor Use this constructor to create and initialize a new instance of the class. To dynamically add a control to a page, create a new object, set its properties, and then add it to the collection of a container control such as .

Initializes a new instance of the class.

2.0.0.0 Method 2.0.0.0 System.Void This method is called by the ASP.NET infrastructure to notify any controls that use composition-based implementation, including controls that derive from and to create any child controls they contain in preparation for postback or rendering.

Clears the current child controls collection, and rebuilds it by calling the method.

Method System.Void The method creates controls, associates them with the corresponding objects from the current site map provider, and adds the nodes to the collection. The method begins by finding the , and then walks up the hierarchical tree of objects, creating a for each one until the is reached. After each is created, but before it is bound to its corresponding , the method is called. The method applies any templates or styles defined for a particular node type and creates and initializes any child controls that the contains. Finally, the method adds the child controls of the to the collection. After each is initialized, the method is called. Then the is bound to its corresponding , and is called. The method is called from the method. Classes that extend the control override the method to alter how the controls are created or added to the control. The manipulation of individual node items is performed in the method, and most classes that extend override that method only.

Examines the site map structure provided by the and builds a child controls collection based on the styles and templates defined for the functional nodes.

2.0.0.0 Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.NotifyParentProperty(true) System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Content) System.ComponentModel.DefaultValue(null) System.Web.UI.WebControls.Style To be added. Use the property to control the appearance of the display text for the navigation path node that represents the currently displayed page. By default, the display text is that specified in the property of the that represents the page. Common style settings include custom background color, foreground color, font properties, and node spacing. For nodes, style properties are merged into a single style, in the following order: or, if the currently displayed page is the root node, . If you set the node font style to a strikeout or overline style, the default underline style of the node is not displayed unless it is explicitly set to true. If a property is defined, the property is ignored.

Gets the style used for the display text for the current node.

2.0.0.0 Property System.ComponentModel.Browsable(false) System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.Web.UI.TemplateContainer(typeof(System.Web.UI.WebControls.SiteMapNodeItem), System.ComponentModel.BindingDirection.OneWay) System.ComponentModel.DefaultValue(null) System.Web.UI.ITemplate To be added. Set the to an object to use an control or some other control, such as a , as the current node's user interface element instead of a string. If the property is set, the template overrides both the current navigation node text displayed and any applied to it. If the currently displayed page corresponds to the root node, however, the or is used. You can declaratively set the property to any Web server control, and the ASP.NET infrastructure performs the necessary steps to wrap the Web server control as an object. However, Web server controls do not implement the interface; therefore, when you work with the properties programmatically, you must write an wrapper for any template code. Then, the property is set to an instance of the wrapper.

Gets or sets a control template to use for the node of a site navigation path that represents the currently displayed page.

2.0.0.0 Method System.Void The control is designed to retrieve its data directly from a site map provider by using the property. Do not use the control to bind to ASP.NET data source controls, and do not call the method explicitly.

Binds a data source to the control and its child controls.

2.0.0.0 Method System.Void The method determines the functional type of node that the item represents by checking the , and applies any templates or styles that are defined for that kind of node. If the has a item type, a child control is created, and the and may be applied. If the is set, its is applied to the node. In instead the is set, it is merged with any defined and applied. Finally, if no templates or styles are defined, a basic control is created and initialized with values from the node. If the has a item type, either a or child control is created, depending on the return value of . Then either the or may be applied. If the is set, its is applied to the node. If instead the is set, it is merged with any defined and applied. If the has a item type, a child control is created and the and may be applied. If the is set, its is applied to the node. If instead the is set, it is applied. Finally, if the has a item type, a child control is created and the and are applied according to the same general rules defined for a node type. Override the method to manipulate individual objects. If the design of the class requires more extensive control over how the objects are created and added to the control, override the method.

Populates a , which is a Web server control that represents a , with a set of child controls based on the node's function and the specified templates and styles for the node.

The to initialize. 2.0.0.0 Event System.Web.UI.WebControls.SiteMapNodeItemEventHandler For more information about handling events, see Handling and Raising Events.

Occurs when a is created by the and is associated with its corresponding . This event is raised by the method.

2.0.0.0 Event System.Web.UI.WebControls.SiteMapNodeItemEventHandler For more information about handling events, see Handling and Raising Events.

Occurs after a has been bound to its underlying data by the . This event is raised by the method.

2.0.0.0 Method System.Void This method is used primarily by the .NET Framework infrastructure and is not intended to be used directly from your code. However, control developers can override this method to specify how a custom server control restores its view state. For more information, see ASP.NET State Management Overview. The method restores the view-state information saved during a previous request.

Restores view-state information from a previous request that was saved with the method.

An that represents the control state to be restored. 2.0.0.0 Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.NotifyParentProperty(true) System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Content) System.ComponentModel.DefaultValue(null) System.Web.UI.WebControls.Style To be added. Use the property to control the appearance of the display text for all navigation path nodes rendered by the control. By default, the display text is that specified in the property of the that represents the page. Common style settings include custom background color, foreground color, font properties, and node spacing. For nodes, style properties are merged into a single style, in the following order: or , depending on the node type. If you set the node font style to a strikeout or overline style, the default underline style of the node is not displayed unless it is explicitly set to true. If the is defined, it is initially applied to each node. If an additional style is defined for a particular type of node, such as the root node or current node, this style supersedes the general style specified in the property. If a template is defined for a particular type of node, it supersedes all defined styles for that node.

Gets the style used for the display text for all nodes in the site navigation path.

2.0.0.0 Property System.ComponentModel.Browsable(false) System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.Web.UI.TemplateContainer(typeof(System.Web.UI.WebControls.SiteMapNodeItem), System.ComponentModel.BindingDirection.OneWay) System.ComponentModel.DefaultValue(null) System.Web.UI.ITemplate To be added. Set the to an object to use an or some other control, such as a , as a user interface element for all navigation path nodes. If the property is set, the template overrides both the navigation node text displayed and any applied to it. For the current and root nodes, if a or is set, these templates override the . You can declaratively set the property to any Web server control, and the ASP.NET infrastructure performs the necessary steps to wrap the Web server control as an object. However, Web server controls do not implement the interface; therefore, when you work with the properties programmatically, you must write an wrapper for any template code. Then, the property is set to an instance of the wrapper.

Gets or sets a control template to use for all functional nodes of a site navigation path.

2.0.0.0 Method System.Void To be added.

Overrides the method of the class and raises the event.

An that contains event data. 2.0.0.0 Method System.Void The event is raised after the control creates a , which is a Web server control that represents a , and associates it to a . The method is called before the created node item is bound to its data. This allows you to provide an event-handling method that performs a custom routine whenever a is created. Raising an event invokes the event handler through a delegate. For more information, see Raising an Event. The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Raises the event of the control.

A that contains event data. 2.0.0.0 Method System.Void The event is raised when the control binds to the data provided by its . This allows you to provide an event-handling method that performs a custom routine, such as updating a database or the displayed content, whenever this event occurs. Raising an event invokes the event handler through a delegate. For more information, see Raising an Event. The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Raises the event of the control.

A that contains event data. 2.0.0.0 Property System.Web.UI.Themeable(false) System.ComponentModel.DefaultValue(-1) System.Int32 To be added. The property governs how many levels of parent nodes are displayed by the control above the current context node. By default, all parent and ancestor nodes above the current context node are displayed. The value of this property is stored in view state. This property cannot be set by themes or style sheet themes. For more information, see and ASP.NET Themes Overview.

Gets or sets the number of levels of parent nodes the control displays, relative to the currently displayed node.

2.0.0.0 Property System.ComponentModel.DefaultValue(System.Web.UI.WebControls.PathDirection.RootToCurrent) System.Web.UI.WebControls.PathDirection To be added. Set to if you want to display the navigation path from left to right; the navigation path appears as a progression from left to right of site map nodes. In other words, the root node is at the leftmost position, each subsequent node is in the next position to the right, and the current node is in the rightmost position. Set to if you want to display the navigation path from right to left. In other words, the node order is reversed so that the root node displays at the rightmost position and the current node displays at the leftmost position. While not as common, this ordering can be used for localizing Web Forms pages and the control for languages that read from right to left. The value of this property is stored in view state.

Gets or sets the order that the navigation path nodes are rendered in.

2.0.0.0 Property System.ComponentModel.Localizable(true) System.ComponentModel.DefaultValue(" > ") System.String To be added. If the is defined, it is applied to the property. However, if a property is defined, both the and properties are ignored. The value of this property is stored in view state. The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and ASP.NET Globalization and Localization.

Gets or sets the string that delimits nodes in the rendered navigation path.

Gets the style used for the string.

2.0.0.0 Property System.ComponentModel.Browsable(false) System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.Web.UI.TemplateContainer(typeof(System.Web.UI.WebControls.SiteMapNodeItem), System.ComponentModel.BindingDirection.OneWay) System.ComponentModel.DefaultValue(null) System.Web.UI.ITemplate To be added. Set the to an object to use an or some other control, such as a , as the path delimiter between navigation nodes instead of the string. If the property is set, the template overrides both the text displayed and any applied to it. You can declaratively set the property to any Web server control, and the ASP.NET infrastructure performs the necessary steps to wrap the Web server control as an . However, Web server controls do not implement the interface; therefore, when you work with the properties programmatically, you must write an wrapper for any template code. Then, the property is set to an instance of the wrapper.

Gets or sets a control template to use for the path delimiter of a site navigation path.

2.0.0.0 Property System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Hidden) System.ComponentModel.Browsable(false) System.Web.SiteMapProvider To be added. The property specifies an instance of a site map provider to use with the control. This provider may be different from the provider identified by the property, if set.

Gets or sets a that is associated with the Web server control.

2.0.0.0 Method 2.0.0.0 System.Void To be added.

To be added.

To be added. Method 2.0.0.0 System.Void To be added. The control overrides the method to perform its accessibility rendering, if the property is not set to .

Renders the nodes in the control.

Property System.ComponentModel.DefaultValue(false) System.Boolean To be added. The node that represents the currently displayed page is the . Its property specifies the text to display for the current node, and its property is used to create a hyperlink. By default, no hyperlink is rendered for the current page to prevent erroneous form posts. The value of this property is stored in view state.

Indicates whether the site navigation node that represents the currently displayed page is rendered as a hyperlink.

2.0.0.0 Property System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.ComponentModel.NotifyParentProperty(true) System.ComponentModel.DesignerSerializationVisibility(System.ComponentModel.DesignerSerializationVisibility.Content) System.ComponentModel.DefaultValue(null) System.Web.UI.WebControls.Style To be added. Use the property to control the appearance of the display text for the root node of the navigation path. By default, the display text is that specified in the property of the that represents the page. Common style settings include custom background color, foreground color, font properties, and node spacing. For nodes, style properties are merged into a single style, in the following order: or , depending on the node type. If you set the node font style to a strikeout or overline style, the default underline style of the node is not displayed unless it is explicitly set to true. If a property is defined, the property is ignored.

Gets the style for the root node display text.

2.0.0.0 Property System.ComponentModel.Browsable(false) System.Web.UI.PersistenceMode(System.Web.UI.PersistenceMode.InnerProperty) System.Web.UI.TemplateContainer(typeof(System.Web.UI.WebControls.SiteMapNodeItem), System.ComponentModel.BindingDirection.OneWay) System.ComponentModel.DefaultValue(null) System.Web.UI.ITemplate To be added. Set the to an object to use an control or some other control, such as a as the root node's user interface element instead of a string. If the property is set, the template overrides both the root navigation node text displayed and any applied to it. The template also overrides the and properties if the root page is the currently displayed page. You can declaratively set the property to any Web server control, and the ASP.NET infrastructure performs the necessary steps to wrap the Web server control as an . However, Web server controls do not implement the interface; therefore, when you work with the properties programmatically, you must write an wrapper for any template code. Then, the property is set to an instance of the wrapper.

Gets or sets a control template to use for the root node of a site navigation path.

2.0.0.0 Method System.Object View state is the accumulation of the values of a server control's properties. These values are automatically placed in the server control's property, which is an instance of the class. The value of this property is then persisted to a string object after the save state stage of the server control life cycle. When view state is saved, this string object is returned to the client as a variable that is stored in an Hidden HTML element. When you author custom server controls, you can improve efficiency by overriding this method and modifying your server control's property.

Saves changes to view state for the control.

Returns the server control's current view state. If there is no view state associated with the control, this method returns null. 2.0.0.0 Property System.Web.UI.Themeable(false) System.ComponentModel.DefaultValue(true) System.Boolean To be added. The most common scenario is when a Title HTML attribute exists for an HTML A Href hyperlink. For example, Microsoft Internet Explorer 4.0 and later and Netscape 6.0 and later implement the Title attribute as a hovering ToolTip, while Opera 3.0 and later implements the Title attribute as both a ToolTip and a caption in Opera's toolbar area. Not all clients display ToolTips for additional hyperlink attributes. The value of this property is stored in view state. This property cannot be set by themes or style sheet themes. For more information, see and ASP.NET Themes Overview.

Gets or sets a value indicating whether the control writes an additional hyperlink attribute for hyperlinked navigation nodes. Depending on client support, when a mouse hovers over a hyperlink that has the additional attribute set, a ToolTip is displayed.

2.0.0.0 Property System.Web.UI.Themeable(false) System.ComponentModel.DefaultValue("") System.String To be added. The control uses a as a source for the site map data it renders. If the property is not set, the control uses the provider identified by the property, which is the default defined for the site in the configuration hierarchy, typically the . Setting the property directs the control to render the site map data that the provider defines. The control works directly with a and its objects to display site map information. Other controls, such as and , require a data abstraction, provided by the class, to display the same site navigation information. The value of this property is stored in view state. This property cannot be set by themes or style sheet themes. For more information, see and ASP.NET Themes Overview.

Gets or sets the name of the used to render the site navigation control.

2.0.0.0 Property System.ComponentModel.Localizable(true) System.String To be added. is a property that you can set to make a Web page more or less accessible to users of screen readers. Web sites that contain content that repeats on multiple pages, such as controls that display site map data, can provide a mechanism that allows users of screen readers to skip the repeated content so that it is not read aloud. The control provides the property as a way for the entire control to be skipped by screen readers. If the property is set, an invisible image with alternate text is rendered, giving the user the option to jump to the end of the content. Screen readers read the alternate text aloud but the image does not disturb the visual flow of the page. The property is set to "Skip Navigation Links" by default, which makes screen readers skip the control. If you want to disable this behavior, set the property to . The value of this property is stored in view state. The value of this property, when set, can be saved automatically to a resource file by using a designer tool. For more information, see and ASP.NET Globalization and Localization.

Gets or sets a value that is used to render alternate text for screen readers to skip the control's content.

2.0.0.0 Method System.Void To be added.

Tracks changes to the control's view state.

2.0.0.0