In this topic:

• Introduction

• Specifying the Starting Node

• Retrieving Site Map Data

• Declarative Syntax

Introduction

The System.Web.UI.WebControls.SiteMapDataSource control is a data source to the site map data that is stored by the site map providers that are configured for your site. The System.Web.UI.WebControls.SiteMapDataSource enables Web server controls that are not specifically site navigation controls, such as the System.Web.UI.WebControls.TreeView, System.Web.UI.WebControls.Menu, and System.Web.UI.WebControls.DropDownList controls, to bind to hierarchical site map data. You can use these Web server controls to display a site map as a table of contents or to actively navigate a site. Alternatively, you can use the System.Web.UI.WebControls.SiteMapPath control, which is designed specifically as a site navigation control and therefore does not need an instance of the System.Web.UI.WebControls.SiteMapDataSource control.

Specifying the Starting Node

The System.Web.UI.WebControls.SiteMapDataSource binds to site map data and presents its view based on a specified starting node in the site map hierarchy. By default, it is the root node of the hierarchy but it can also be any node within the hierarchy. The starting node is identified by the values of several System.Web.UI.WebControls.SiteMapDataSource properties as follows:

If the SiteMapDataSource.StartingNodeOffset property is set to a value other than 0, it affects the starting node and with it the site map data hierarchy that is exposed by the System.Web.UI.WebControls.SiteMapDataSource control. The negative or positive integer value of the SiteMapDataSource.StartingNodeOffset identifies the number of levels up or down the site map hierarchy from the starting node that is identified by the SiteMapDataSource.StartFromCurrentNode and SiteMapDataSource.StartingNodeUrl properties to offset the starting node of the subtree that is exposed by data source control.

If the SiteMapDataSource.StartingNodeOffset property is set to a negative number -n, the starting node of the subtree that is exposed by the data source control is the ancestor node n hierarchical levels above the identified starting node. If the value n is greater than the number of ancestor levels in the hierarchical tree, the starting node of the subtree is the root node of the site map hierarchy.

If the SiteMapDataSource.StartingNodeOffset property is set to a positive number +n, the starting node of the subtree that is exposed is a child node n levels below the identified starting node. Because more than one branch of child nodes might exist in the hierarchy, the System.Web.UI.WebControls.SiteMapDataSource attempts to resolve a child node directly on the path between the identified starting node and the node that represents the currently requested page, if possible. If the node that represents the currently requested page is not in the subtree of the identified starting node, the value of the SiteMapDataSource.StartingNodeOffset property is ignored. If the node that represents the currently requested page is less than n levels below the identified starting node, the currently requested page node is used as the starting node.

Retrieving Site Map Data

Site map data is retrieved from an System.Web.SiteMapProvider object, such as System.Web.XmlSiteMapProvider, which is the default site map provider for ASP.NET. You can specify any provider that is configured for your site to provide the site map data to the System.Web.UI.WebControls.SiteMapDataSource and can obtain the list of available providers by accessing the System.Web.SiteMap.Providers collection.

Like all data source controls, every instance of a System.Web.UI.WebControls.SiteMapDataSource is associated with a single helper object, known as a data source view. The System.Web.UI.WebControls.SiteMapDataSourceView is a view on the site map data, according to the properties of the data source, and is retrieved by calling the SiteMapDataSource.GetHierarchicalView(string) method. The System.Web.UI.WebControls.SiteMapDataSourceView maintains the System.Web.SiteMapNodeCollection object that the controls bind to.

By default, the starting node is the root node of the hierarchy, but you can set the starting node to any node. The starting point can be a node that is relative to the current position in the site map or to an absolute position. You can specify the starting node by setting the SiteMapDataSource.StartingNodeUrl property.

The System.Web.UI.WebControls.SiteMapDataSource is specialized for navigation data, and does not support common data source operations such as sorting, filtering, paging, caching, or data record operations such as updates, insertions or deletions.

Declarative Syntax

<asp:SiteMapDataSource
    EnableTheming="True|