Programmatically accessing Site Map – Part 4

In previous Part, we only provided a cursory introduction to both the site map file and navigation Web controls’ functionalities and capabilities. In this part of the article series we’ll turn our attention to programmatically working with the site map information, as well as looking at the SiteMapPath navigation Web controls in detail.

The Site Map…

The precise syntax for the site map XML file can be seen as. A pictorial representation of the site structure used for these demos can be seen below…

 

Programmatically Working with the Site Map

A site map is a collection of related site map nodes. Each site map node typically contains a title, URL, and description. The image shown above is an example of a site map, with each box representing a site map node. ASP.NET does not require a particular format for specifying the site map, although it does provide a default choice that uses an XML-formatted file. (The XML file’s specifics were examined in Part 1.)

ASP.NET provides a class called SiteMap that offers read-only, programmatic access to the site map. This class is used internally by the two controls we’ll be examining in this article:

• SiteMapPath – renders a breadcrumb based on the page being visited and it’s position in the site structure. Specifically, the SiteMapPath starts from the node returned by the SiteMap.CurrentNode property and walks up the hierarchy until it reaches the root.
• SiteMapDataSource – this control creates a hierarchical datasource that mirrors the structure of the site map. In order to display site map information in other Web controls, such as the TreeView or Menu, the Web controls don’t query the site map directly; rather, they are bound to a SiteMapDataSource control, which handles reading in the site map structure. (We’ll examine the SiteMapDataSource control in greater detail in future articles in this series.)

The SiteMap class has two germane properties: RootNode and CurrentNode. Both of these properties return SiteMapNode instances. The SiteMapNode class represents a node defined in the site map and has properties describing the node – Title, Url, and Description – as well as properties that allow for programmatic movement through the hierarchy – ParentNode, ChildNodes, NextSibling, PreviousSibling, and so on.

You can utilize the SiteMap class in your own ASP.NET pages. For example, we could display Next, Previous, and Up links in each page by adding three HyperLink controls to the site’s master page along with a bit of code that checks to see if the CurrentNode has a NextSibling, PreviousSibling, or ParentNode. Specifically, you’d add the following markup to your master page:

[<asp:HyperLink ID="lnkPrev" runat="server">Prev</asp:HyperLink>] | [<asp:HyperLink ID="lnkUp" runat="server">Up</asp:HyperLink>] | [<asp:HyperLink ID="lnkNext" runat="server">Next</asp:HyperLink>]

The master page’s Page_Load event handler would look something like:

If SiteMap.CurrentNode IsNot Nothing Then     'Set the next/previous/up links     If SiteMap.CurrentNode.PreviousSibling IsNot Nothing Then         lnkPrev.NavigateUrl = SiteMap.CurrentNode.PreviousSibling.Url         lnkPrev.Text = "< Prev (" & SiteMap.CurrentNode.PreviousSibling.Title & ")"     Else         lnkPrev.NavigateUrl = String.Empty         lnkPrev.Text = "< Prev"     End If     If SiteMap.CurrentNode.ParentNode IsNot Nothing Then         lnkUp.NavigateUrl = SiteMap.CurrentNode.ParentNode.Url         lnkUp.Text = "Up (" & SiteMap.CurrentNode.ParentNode.Title & ")"     Else         lnkUp.NavigateUrl = String.Empty         lnkUp.Text = "Up"     End If     If SiteMap.CurrentNode.NextSibling IsNot Nothing Then         lnkNext.NavigateUrl = SiteMap.CurrentNode.NextSibling.Url         lnkNext.Text = "(" & SiteMap.CurrentNode.NextSibling.Title & ") Next >"     Else         lnkNext.NavigateUrl = String.Empty         lnkNext.Text = "Next >"     End If End If

This would add to each page that inherited the master page the three hyperlinks, Next, Up, and Previous, as shown in the screenshot below.

 

(The markup and code needed to accomplish this is downloadable at the end of this article…)

Displaying Breadcrumbs with the SiteMapPath Control

The SiteMapPath control displays a breadcrumb, showing the user their position in the site structure. The output of the SiteMapPath control is determined by three factors:

• The site’s structure, as defined by the site map,
• The page being visited, and
• The property values of the SiteMapPath control

When a page with a SiteMapPath control is visited, the SiteMapPath control attempts to map the page’s URL to the url value of a site map node defined in the site map. If a match is found, the control walks up the structure to the root, emitting the following output: RootNode > ParentNode > ... > ParentNode > CurrentNode. Here CurrentNode is the title of the site map node that maps to the URL of the current page request; the RootNode and ParentNodes are rendered as hyperlinks if the site map node has a URL value defined in the site map. A SiteMapPath control on the History Books page (Books/History.aspx) would render as Home > Books > History, with Home and Books rendered as links back to Default.aspx and Books/Default.aspx, respectively. Visiting Books/Default.aspx, the SiteMapPath renders as just Home > Books.

Clearly the output of the SiteMapPath is dependent upon both the site map itself and the page being visited. The SiteMapPath’s output can also be customized through the control’s properties. There are the standard WebControl formatting properties – BackColor, Font, ForeColor, and so on – as well as some SiteMapPath-specific settings, including:

• PathDirection – can have one of two values – RootToCurrent (the default) or CurrentToRoot. With RootToCurrent, the breadcrumb on the History Books page is rendered as Home > Books > History; with CurrentToRoot, the output would instead be History > Books > Home.
• PathSeparator – specifies the string used to separate each node in the breadcrumb; defaults to >
• RenderCurrentNodeAsLink – a Boolean property that specifies whether or not the CurrentNode should be rendered as a link; defaults to False.
• ParentLevelsDisplayed – an integer value that can be set to limit how far up the hierarchy the breadcrumb displays. By default, this property has a value of -1, meaning that there is no limit; setting this to 1 on the History Books page would render the breadcrumb Books > History. Home is not included because the SiteMapPath control only walks up to at most 1 parent level – from History to Book.
• ShowToolTips – if a site map node has a description value, the description is shown as a tooltip for each breadcrumb node if this property is set to True (the default).

There are also style properties for setting BackColor, Font, ForeColor, and so on, for various pieces of the SiteMapPath control. The NodeStyle property can be used to customize the appearance of the nodes in the breadcrumb; RootNodeStyle and CurrentNodeStyle can be used to further customize the first and last nodes in the breadcrumb. For the artistically inclined, like yours truly, oftentimes the simplest and most aesthetically-pleasing way to format the SiteMapPath control is to use it’s Auto Format wizard, which is available through the control’s smart tag.

Customizing the Rendered Output with Templates

The SiteMapPath contains four templates that allow for the rendered output to be further customized. Templates allow for a mix of static HTML markup, Web controls, and databinding syntax; if you’ve used the DataList or Repeater controls before then you’re already familiar with templates. Templates in ASP.NET 2.0 are fundamentally the same as templates in ASP.NET 1.x, except that ASP.NET 2.0 introduces some new, more terse syntax for databinding expressions. For example, in ASP.NET 1.x you had to use the syntax <%# DataBinder.Eval(Container.DataItem, PropertyName) %> to get the value of a column. In ASP.NET 2.0 that old syntax still works, but you can optionally use the shorter version, <%# Eval(PropertyName) %>. (For more on the databinding enhancements in ASP.NET 2.0 be sure to check out Simplified and Extended DataBinding Syntax in ASP.NET 2.0.)

By default the SiteMapPath renders the root and parent nodes as regular hyperlinks so that when a user clicks the link they are immediately whisked back up the control hierarchy. However, you may want to do some server-side processing before sending the user on their merry way – maybe you want to record where the user is going, or automatically save any changes they made on the page. Such functionality can be accomplished by using a template and having the node rendered as a LinkButton.

For example, if you wanted just the SiteMapPath’s root node to be rendered as a LinkButton, you could add a <RootNodeTemplate> to the SiteMapPath control with the following markup:

<asp:SiteMapPath ID="SiteMapPath1" runat="server">   <RootNodeTemplate>      <asp:LinkButton ID="LinkButton1" runat="server"                      Text='<%# Eval("title") %>'                      CommandArgument='<%# Eval("url") %>'                      OnCommand="LinkButton1_Command">      </asp:LinkButton>   </RootNodeTemplate> </asp:SiteMapPath>

This markup adds a LinkButton control to the SiteMapPath whose Text property is assigned to the corresponding SiteMapNode‘s Title property. When the LinkButton is clicked a postback ensues and the control’s Command event fires, triggering the LinkButton1_Command event handler. The Url property of the SiteMapNode is passed to this event handler through the CommandArgument property. In the event handler you could do whatever server-side processing was needed and then send the user onto the page they requested with Response.Redirect(e.CommandArgument).