Home   |   QuickStart Welcome   |   ASP.NET   |   Web Services   |   How Do I...?   
  |   I want my samples in...      

ASP.NET 2.0 Quickstart Tutorials

SiteMapPath

The SiteMapPath control displays a list of links representing the user�s current page and the hierarchal path back to the root of the website. This functionality is sometimes referred to as a breadcrumb for the user.

SiteMapPath Control and Data Retrieval

The SiteMapPath control relies on a SiteMapProvider to retrieve the data that it will display. Unlike the Menu or Treeview control the SiteMapPath control does NOT use a SiteMapDataSource control and can not be bound to other hierarchal datasource controls.

The default SiteMap provider will automatically be used by the control or you can set the SiteMapProvider property on the control to point to any provider already configured in the web.config file. The SiteMapPath control will only display on a page whose URL is contained within the specified SiteMapPath provider. NOTE: This is a typical error that developers encounter � so if the SiteMapPath control does not appear when you run your page check to make sure the page is listed correctly (no typos) in the SiteMapPath providers data store, most commonly an XML file.

The SiteMapPath control will automatically take advantage of the security trimming, URL remapping and Localized Site Map data features of the Site Navigation API.

Note: The samples for this control use Master Pages to provide the information that is used to logon a user. For more information on Master Pages.

Basic SiteMapPath Example

In this sample I have included a SiteMapPath control and a Menu control that both use the same SiteMapPath data. Use the Menu control to navigate to different pages in the web site and see how the display of the SiteMapPath control changes to show different hierarchies. The SiteMapPath XML file containing the site structure is also included for your reference. The XML file contains the optional Description SiteMapNode element which is displayed as answer tips by the SiteMapPath and Menu control.

VB SiteMapPathBasic.aspx
Run Sample View Source

SiteMapPath Behaviors Example

The SiteMapPath provides properties to change the most common display options. In this sample we demonostrate how to:
  • Set the ShowToolTips=false so that the description text from the SiteMap Provider XML file is not automatically displayed.
  • Set the ParentLevelsDisplayed=3 which will display the current page and 3 levels of the hierarchy. By default this property is set to -1 and all parent levels are displayed.
  • Set RenderCurrentNodeAsLink=true so that the current page displayed in the hierarchy will appear as a link instead of text.
  • Set PathDirection=CurrentToRoot which will change the order in which the links the appear. The default is start from the highest node and go to the current page, with this setting the links will be displayed starting at the current page and ending at the highest node displayed.
  • Set the PathSeparator=":" the default is ">"
VB SiteMapPathBehaviors.aspx
Run Sample View Source

SiteMapPath Appearance

You can change the appearance of a SiteMapPath by setting style properties on the control; using a skin/theme file or by templating the nodes of the SiteMapPath.

SiteMapPath StyleExample

In addition to the standard web control style properties, the SiteMapPath control supports setting separate style properties for:
  • NodeStyle: The NodeStyle is used for all parent nodes displayed in the hierarchy except the absolute RootNode of the SiteMapProvider data source. The NodeStyle merges with the standard web control style properties in the event of a conflict the NodeStyle will be displayed.


  • CurrentNodeStyle: The CurrentNodeStyle is applied to the node representing the current page being displayed. The appearance of the current node is also affected by the RenderCurrentNodeAsLink property. The CurrentNodeStyle merges with the standard web control style properties and the NodeStyle properties, in the event of a conflict the CurrentNodeStyle will be applied.


  • RootNodeStyle: The RootNodeStyle is applied to the absolute root of the SiteMap Provider hierarchy. As a result, the RootNodeStyle may not be displayed on every page of your website depending on how many levels of the hierarchy are displayed. In the event that the RootNode is the current page being displayed then the CurrentNodeStyle will be applied. . The RootNodeStyle merges with the standard web control style properties and the NodeStyle properties, in the event of a conflict the RootNodeStyle will be applied.


  • PathSeparatorStyle: The PathSeparatorStyle is applied to the PathSeparator property value that is used to separate the nodes. The PathSeparatorStyle merges with the standard web control style properties in the event of a conflict the PathSeparatorStyle will be displayed.




You can also use the themes feature Themes and Skins feature to control the appearance of the SiteMapPath control.

VB SiteMapPathStyles.aspx
Run Sample View Source

SiteMapPath Template Example

In addition to styles, you can use templates to further control the look and feel of the SiteMapPath control. Templates give you full control over the HTML that is rendered for a specific part of the control. When you chose to template one of the nodes you are responsible for databinding the pertinent information (e.g. Title, URL and Description) from the SiteMap Provider to the appropriate controls on your page. For example if you want to databind the title to a label in one of the Node Templates you can type the following expression: Text='<%# Eval("title") %>'>.

The SiteMapPath supports the following templates:

  • NodeTemplate: Displayed for nodes in the hierarchy.


  • CurrentNodeTemplate: Displayed for the corresponding node in the hierarchy to the page that is being displayed.


  • RootNodeTemplate: Displayed when the absolute root of the SiteMap hierarchy is returned. In the event that the RootNode is the current page then the CurrentNode or CurrentNodeTemplate will be displayed.


  • PathSeparatorTemplate: Displayed between the various nodes being displayed and is used in place of PathSeparator text value.


In the following sample the PathSeparatorTemplate displays an image. The CurrentNodeTemplate displays the phrase �You are at �title�!� by databinding a label to the title value. The RootNodeTemplate displays the static phrase �RootNode� because it is not databound to any SiteMap node values.

VB SiteMapPathTemplates.aspx
Run Sample View Source