<%@ Page Language="C#" MasterPageFile="~/aspnet/section.master" %> <%@ Register TagPrefix=Acme Namespace=Acme %> <%@ Register TagPrefix="Acme" TagName="SourceRef" Src="~/util/SrcRef.ascx"%>

SiteMapDataSource

The SiteMapDataSource control enables you to declaratively data bind to site navigation data in your pages. The SiteMapDataSource control is associated to a data-bound control through the control's DataSourceID property. For general information on site navigation in ASP.NET, refer to the Creating a Site Navigation Hierarchy topic of this tutorial.

The following example shows a SiteMapDataSource control bound to a TreeView control in a master page. Note that the TreeView control automatically binds to the Title and Url of a SiteMapNode, so it is not necessary to explicitly define the Databindings property of the TreeView.


You can set the ShowStartingNode property to determine whether the SiteMapDataSource exposes the starting node as the root of the site map, or whether it starts from the child nodes of the root node instead. The example below sets ShowStartingNode to false.


The previous example shows the whole site map, starting from the root node (the default starting node for SiteMapDataSource). You can also configure a specific starting node for the data source by setting the StartingNodeUrl property to the Url of a node in the site map. You can also set the StartingNodeOffset property of SiteMapDataSource to dictate a number of levels up or down from the current starting node to set a new starting node for the data source. If the StartingNodeOffset is negative (-N), the SiteMapDataSource starts N levels above the current starting node, traveling up the parent node hierarchy. If the StartingNodeOffset is positive (N), the SiteMapDataSource starts N levels below the current starting node, travelling down the child hierarchy toward the current node in the site map.

The example below shows a sample usage for StartingNodeOffset and StartingNodeUrl. Note that when you click one of the Chapter or Paragraph nodes in the tree, the starting node for the SiteMapDataSource in SiteMap.master becomes the Chapter node, which 2 levels below the ~/Home.aspx node, along the path toward the currently selected chapter or paragraph node in the site map. Because ~/Home.aspx is the Url for the root node in the site map, it is not strictly necessary to set StartingNodeUrl here (since the root node is the default starting node for SiteMapDataSource), but it is set here purely for the sake of example.


The StartFromCurrentNode property sets the starting node for the SiteMapDataSource to the current node in the site map. This property is mutually exclusive with the StartingNodeUrl property; one of these may be set at the same time for a SiteMapDataSource. The example below shows a SiteMapDataSource configured with StartFromCurrentNode set to true and ShowStartingNode set to false. This exposes the immediate children of the current node in the site map. A GridView control is bound to this data source for navigating to the children of the current node. Because the SiteMapDataSource supports the IDataSource interface in addition to IHierarchicalDataSource, it is possible to bind tabular or list controls to SiteMapDataSource.


You can define a negative offset for the starting node (relative to the current node) by defining the StartingNodeOffset property. A positive offset is not supported when the starting node is the current node. The example below demonstrates a DropDownList control inside the CurrentNodeTemplate of a SiteMapPath control, bound to a SiteMapDataSource with StartingNodeOffset set to -1, StartFromCurrentNode set to true, and ShowStartingNode set to false. This has the effect of showing the current node and its sibling nodes in the DropDownList. The DropDownList SelectedValue property is data-bound to the Url of the CurrentNode in the site map (using the Site Navigation API), so that the DropDownList reflects the current node as selected by default. You can change the value in this DropDownList to navigate to one of the sibling nodes of the current node.