Navigation Controls
Applies to: SharePoint Foundation 2010
The chrome for a Microsoft SharePoint Foundation website includes a set of controls whose purpose is to help users navigate the site, making it easier for them to find important content, know their current position in the site, and quickly backtrack to a previous location.
You can find the markup for these controls in the master page for the website's home page. In SharePoint Foundation 2010, the primary master page for both content and application pages is v4.master.
Note
For more information about default master pages, see Default Master Pages in SharePoint Foundation.
Four principal aids to navigation are defined in v4.master:
Breadcrumb
Top link bar
Quick Launch
Tree view
Breadcrumb
The breadcrumb is a navigational element that appears at the top of content pages in a SharePoint Foundation website, on the ribbon, just to the right of Site Actions. It is marked by an icon that looks like a folder with an up arrow superimposed. When your mouse pointer hovers over the icon, a tooltip displays "Navigate Up." When you click the icon, a pop-out menu appears. This menu shows your current position in the site hierarchy. Clicking any of the links that precede your current position opens that location, providing a quick path back to your starting point.
In v4.master, the breadcrumb is defined by the following markup:
Note
To make the markup easier to read, resource expressions ("$Resources:wss,resource_id") are replaced by their localized string values.
<asp:contentplaceholder id="PlaceHolderGlobalNavigation" runat="server">
<SharePoint:PopoutMenu
runat="server"
ID="GlobalBreadCrumbNavPopout"
IconUrl="/_layouts/images/fgimg.png"
IconAlt="Navigate Up"
IconOffsetX=0
IconOffsetY=112
IconWidth=16
IconHeight=16
AnchorCss="s4-breadcrumb-anchor"
AnchorOpenCss="s4-breadcrumb-anchor-open"
MenuCss="s4-breadcrumb-menu">
<div class="s4-breadcrumb-top">
<asp:Label
runat="server"
CssClass="s4-breadcrumb-header"
Text="This page location is:" />
</div>
<asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">
<SharePoint:ListSiteMapPath
runat="server"
SiteMapProviders="SPSiteMapProvider,SPContentMapProvider"
RenderCurrentNodeAsLink="false"
PathSeparator=""
CssClass="s4-breadcrumb"
NodeStyle-CssClass="s4-breadcrumbNode"
CurrentNodeStyle-CssClass="s4-breadcrumbCurrentNode"
RootNodeStyle-CssClass="s4-breadcrumbRootNode"
NodeImageOffsetX=0
NodeImageOffsetY=353
NodeImageWidth=16
NodeImageHeight=16
NodeImageUrl="/_layouts/images/fgimg.png"
RTLNodeImageOffsetX=0
RTLNodeImageOffsetY=376
RTLNodeImageWidth=16
RTLNodeImageHeight=16
RTLNodeImageUrl="/_layouts/images/fgimg.png"
HideInteriorRootNodes="true"
SkipLinkText="" />
</asp:ContentPlaceHolder>
</SharePoint:PopoutMenu>
<div class="s4-die">
<asp:ContentPlaceHolder id="PlaceHolderGlobalNavigationSiteMap" runat="server" Visible="false">
</asp:ContentPlaceHolder>
</div>
</asp:contentplaceholder>
The first thing to notice about this markup is that the entire breadcrumb is enclosed within a ContentPlaceHolder control (ID="PlaceHolderGlobalNavigation"). This means you have the option to create a content page and add a Content control that overrides the default content that is defined in the master page.
Most of the markup is involved with defining the pop-out menu. As you can see from the markup, the menu is rendered by a PopoutMenu control. This control contains a Label control for the menu header and a ListSiteMapPath control for the hyperlinks that enable users to navigate the website. The ListSiteMapPath control is nested within another ContentPlaceholder control (ID="PlaceHolderTitleBreadcrumb"), so that it can also be overridden in a content page.
The ListSiteMapPath control gets its navigational data from a pair of providers, SPSiteMapProvider and SPContentMapProvider. The first provides data about websites in the site hierarchy; the second provides data about site content, such as lists, libraries, folders, and site pages. Both navigation providers derive from the SiteMapProvider class that is the source for site map data on standard ASP.NET sites.
Note
Navigation providers are declared in the <system.web> section of the web.config file in the root directory of the web application on the path Drive:\inetpub\wwwroot\wss\VirtualDirectories\ Port_Number\web.config.
Top Link Bar
The top link bar is a tabbed strip that appears just below the website's title and description. The first link on the top link bar is the "Home" position. Often this link points to the website where the bar is defined, and the remaining links point to websites lower down in the site hierarchy. However, this standard is not enforced. Any valid URL can be used for a link, and links can be arranged in any order.
A subsite can inherit the top link bar from its parent website. When this is done, the top link bar can provide a consistent navigation experience across several websites. For more information, see How to: Share the Top Link Bar Between Sites.
In v4.master, the top link bar is defined by the following markup:
<asp:ContentPlaceHolder id="PlaceHolderHorizontalNav" runat="server">
<SharePoint:AspMenu
ID="TopNavigationMenuV4"
Runat="server"
EnableViewState="false"
DataSourceID="topSiteMap"
AccessKey="1"
UseSimpleRendering="true"
UseSeparateCss="false"
Orientation="Horizontal"
StaticDisplayLevels="2"
MaximumDynamicDisplayLevels="1"
SkipLinkText=""
CssClass="s4-tn"/>
<SharePoint:DelegateControl
runat="server"
ControlId="TopNavigationDataSource"
Id="topNavigationDelegate">
<Template_Controls>
<asp:SiteMapDataSource
ShowStartingNode="False"
SiteMapProvider="SPNavigationProvider"
id="topSiteMap"
runat="server"
StartingNodeUrl="sid:1002"/>
</Template_Controls>
</SharePoint:DelegateControl>
</asp:ContentPlaceHolder>
Like the markup for the breadcrumb, the markup that defines the top link bar is enclosed within a ContentPlaceHolder control, giving content page designers the option to override the default content with their own.
The top link bar is rendered by an AspMenu control. The menu renders horizontally, a direction that the markup for the control specifies by setting the Orientation property to "Horizontal". The setting for the StaticDisplayLevels property is "2". Normally this setting would mean that if a node on the menu has a child node, it appears one row below the parent node. However, in actual practice child nodes appear to the right of the parent node, at the same level. This effect is caused by the cascading style sheet (CSS) class attached to the menu by the setting of the CssClass property. To make the menu items easier to control with CSS, the markup for the control sets the UseSimpleRendering property to "true".
If the menu structure is deeper than two levels, items on the third level display on a flyout menu, an effect that is controlled by the setting of the MaximumDynamicDisplayLevels property. Because this setting is "1", flyout menus display only one level below the two that appear on the static menu. All additional levels are discarded.
The data source behind the menu is a SiteMapDataSource control. As you can see from the markup, the SiteMapProvider property binds the data source control to an instance of the SPNavigationProvider class, which derives from the SiteMapProvider class.
You might also notice that the value of the ShowStartingNode property is False. This is because the actual starting node is the root of the node tree that forms the top link bar; it serves an internal function and is not meant to be rendered on the page. The value of the StartingNodeUrl property, "sid:1002", is not a proper URL but instead is an expression that points to the SharePoint identifier for the top link bar's root node.
You can retrieve the root node by using the following line of code:
SPNavigationNode toplinkbar = web.Navigation.GetNodeById(1002);
Dim toplinkbar as SPNavigationNode = web.Navigation.GetNodeById(1002)
When you examine this object, you will find that its Title property returns "SharePoint Top Navigation Bar" and its Url property returns "/".
Tip
You can get similar results if you open v4.master in SharePoint Designer 2010 and change the value of ShowStartingNode to True. When you save the change and display the website's home page in your browser, you should see that the first node on the top link bar contains the display text SharePoint Top Navigation Bar.
The SPNavigationNode object that represents the root of the top link bar's node tree has a Children property that returns a collection of SPNavigationNode objects. The objects in this collection represent the visible nodes on the top link bar. The collection is enumerable, so you can easily iterate over it as shown in the following short console application:
using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Navigation;
namespace ConsoleApp
{
class Program
{
static void Main(string[] args)
{
using (SPSite site = new SPSite("https://localhost"))
{
using (SPWeb web = site.OpenWeb())
{
SPNavigationNode toplinkbar = web.Navigation.GetNodeById(1002);
if (toplinkbar != null)
{
foreach (SPNavigationNode node in toplinkbar.Children)
{
Console.Write("| {0} ", node.Title);
}
Console.WriteLine("|");
}
}
}
Console.Write("\nPress ENTER to continue....");
Console.ReadLine();
}
}
}
Imports System
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Navigation
Module ConsoleApp
Sub Main()
Using site As New SPSite("https://localhost")
Using web As SPWeb = site.OpenWeb()
Dim toplinkbar As SPNavigationNode = web.Navigation.GetNodeById(1002)
If toplinkbar IsNot Nothing Then
For Each node As SPNavigationNode In toplinkbar.Children
Console.Write("| {0} ", node.Title)
Next
Console.WriteLine("|")
End If
End Using
End Using
Console.Write(vbCrLf & "Press ENTER to continue....")
Console.Read()
End Sub
End Module
Quick Launch
Quick Launch is a menu of links that can appear on the left side of pages in a website. The menu is intended for navigation within a site and usually has links to lists and document libraries and other site content. It can also include links to external content.
Site owners can enable or hide the Quick Launch menu by accessing the administrative user interface on the Site Actions menu. Developers can do the same thing by writing code. For more information, see How to: Display or Hide Quick Launch.
In v4.master, the markup that defines the Quick Launch menu is nested inside a ContentPlaceHolder control (ID="PlaceHolderLeftNavBar") that also contains markup for the tree view control. As a result, page designers have the option of replacing both navigation controls with their own content. The content pages that are associated with some built-in web templates do substitute other content. The Meeting Workspace template is an example.
The markup for the Quick Launch menu defines two versions, each within a UIVersionedContent control. For one UIVersionedContent control, the value of the UIVersion attribute is "3"; for the other, the value is "4." Which version renders on the page depends on whether site collection administrators have applied the newer user interface to websites in the collection. For more information, see Visual Upgrade.
Note
You can get the version number of the user interface programmatically by accessing the SPWeb.UIVersion property.
Version 4 of the Quick Launch menu is defined by the following markup:
<SharePoint:AspMenu
id="V4QuickLaunchMenu"
runat="server"
EnableViewState="false"
DataSourceId="QuickLaunchSiteMap"
UseSimpleRendering="true"
UseSeparateCss="false"
Orientation="Vertical"
StaticDisplayLevels="2"
MaximumDynamicDisplayLevels="0"
SkipLinkText=""
CssClass="s4-ql" />
The Quick Launch menu appears as a series of headings that may have one or more levels of menu items beneath them. The number of menu levels that are actually rendered on the page depends on the configuration of the AspMenu control that renders the menu.
In the previous example, the value of the StaticDisplayLevels property is "2", meaning that two menu levels are displayed: a heading plus one level below the heading. Additional levels below these two heading can be displayed in a dynamic, flyout menu. How many levels display on the flyout menu is governed by the setting for the MaximumDynamicDisplayLevels property. In this case, the property value is "0", meaning that flyout menus are disabled. Thus if Quick Launch has more than two menu levels, they are not shown.
The DataSourceID property in the markup for the AspMenu control points to a SiteMapDataSource control that is configured by the following markup:
<asp:SiteMapDataSource
SiteMapProvider="SPNavigationProvider"
ShowStartingNode="False"
id="QuickLaunchSiteMap"
StartingNodeUrl="sid:1025"
runat="server" />
As is the case with the data source for the top link bar, the data source for the Quick Launch menu has its ShowStartingNode property set to False. The root node has information about the Quick Launch menu itself and is not intended for display. All other nodes (links) on the menu are children of this node. The value of the StartingNodeUrl property, "sid:10252", indicates the SharePoint identifier for the Quick Launch root node.
You can retrieve the root node by using the following line of code:
SPNavigationNode quicklaunch = web.Navigation.GetNodeById(1025);
Dim quicklaunch as SPNavigationNode = web.Navigation.GetNodeById(1025)
When you examine this object, you will find that its Title property returns "Quick launch" and its Url property returns "/".
The SPNavigationNode object at the root of the node tree has a Children property that returns a collection of SPNavigationNode objects that represent the first level of menu items, the headings. Each heading can also have child nodes, which represent the second level of menu items. Nodes on the second level can have child nodes too, and so on down the tree.
The following console application shows how to walk down the Quick Launch menu, enumerating the items. The application prints the display text for each heading on the Quick Launch menu and then calls a recursive method to print the display text for all menu levels below each heading.
using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Navigation;
namespace ConsoleApp
{
class Program
{
static void Main(string[] args)
{
using (SPSite site = new SPSite("https://localhost"))
{
using (SPWeb web = site.OpenWeb())
{
SPNavigationNode quicklaunch = web.Navigation.GetNodeById(1025);
if (quicklaunch != null)
{
foreach (SPNavigationNode heading in quicklaunch.Children)
{
PrintNode(heading);
Console.WriteLine(new String('-', 10));
}
}
}
}
Console.Write("\nPress ENTER to continue....");
Console.ReadLine();
}
static void PrintNode(SPNavigationNode node)
{
Console.WriteLine(node.Title);
foreach (SPNavigationNode item in node.Children)
PrintNode(item);
}
}
}
Imports System
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Navigation
Module ConsoleApp
Sub Main()
Using site As New SPSite("https://localhost")
Using web As SPWeb = site.OpenWeb()
Dim quicklaunch As SPNavigationNode = web.Navigation.GetNodeById(1025)
If quicklaunch IsNot Nothing Then
For Each heading As SPNavigationNode In quicklaunch.Children
PrintNode(heading)
Console.WriteLine(New String("-", 10))
Next
End If
End Using
End Using
Console.Write(vbCrLf & "Press ENTER to continue....")
Console.Read()
End Sub
Sub PrintNode(ByRef node As SPNavigationNode)
Console.WriteLine(node.Title)
For Each item As SPNavigationNode In node.Children
PrintNode(item)
Next
End Sub
End Module
Tree View
The tree view navigational element is intended to display a hierarchical view of all site content. By default, the tree view is disabled. When it is enabled, it appears in the left navigational area of the page. If Quick Launch is enabled, the tree view appears below it.
An administrator for the website can enable the tree view by going to the Tree View page in the administrative user interface. To view the Tree View page, click Site Actions, and then click Site Settings. Under Look and Feel, click Tree view.
You can enable the tree view in code by setting the SPWeb.TreeViewEnabled property to true.
Like Quick Launch, the tree view has two versions. In v4.master, both versions are rendered by an SPTreeView control nested inside an SPRememberScroll control. The SPTreeView control gets its data from an instance of the SPHierarchyDataSourceControl class.
In v4.master, version 4 is defined by the following markup:
<SharePoint:DelegateControl runat="server" ControlId="TreeViewAndDataSource">
<Template_Controls>
<SharePoint:SPHierarchyDataSourceControl
runat="server"
id="TreeViewDataSourceV4"
RootContextObject="Web"
IncludeDiscussionFolders="true" />
<SharePoint:SPRememberScroll
runat="server"
id="TreeViewRememberScrollV4"
onscroll="javascript:_spRecordScrollPositions(this);"
style="overflow: auto;height: 400px;width: 155px; ">
<SharePoint:SPTreeView
id="WebTreeViewV4"
runat="server"
ShowLines="false"
DataSourceId="TreeViewDataSourceV4"
ExpandDepth="0"
SelectedNodeStyle-CssClass="ms-tvselected"
NodeStyle-CssClass="ms-navitem"
SkipLinkText=""
NodeIndent="12"
ExpandImageUrl="/_layouts/images/tvclosed.png"
ExpandImageUrlRtl="/_layouts/images/tvclosedrtl.png"
CollapseImageUrl="/_layouts/images/tvopen.png"
CollapseImageUrlRtl="/_layouts/images/tvopenrtl.png"
NoExpandImageUrl="/_layouts/images/tvblank.gif">
</SharePoint:SPTreeView>
</SharePoint:SPRememberScroll>
</Template_Controls>
</SharePoint:DelegateControl>
Notice that the data source for the tree view control is an SPHierarchyDataSourceControl object, and that the RootContextObject property of the object is set to "Web." This sets the context in which the tree is rooted. As a result, the tree view renders links to all subsites of the current site, followed by document libraries and lists.
See Also
Tasks
How to: Add a Subsite to the Top Link Bar or Quick Launch Menu
How to: Customize the Display of Quick Launch
Concepts
How to: Share the Top Link Bar Between Sites