Working with Menus and Navigation Objects in SharePoint Server 2010 (ECM)

Article
07/24/2014

Applies to: SharePoint Server 2010

In this article
Horizontal and Vertical Menus
PortalSiteMapDataSource
PortalSiteMapProvider

You declare horizontal and vertical menu instructions for navigation in XML for the master page. Two classes are used to make navigation work: PortalSiteMapDataSource and PortalSiteMapProvider.

The PortalSiteMapProvider object provides the site hierarchy (navigation structure) and monitors the relationship between nodes. The PortalSiteMapDataSource object maps navigation features from the PortalSiteMapProvider and filters navigation elements to determine which are viewable to the user in the horizontal or vertical menus or in breadcrumbs.

Horizontal and Vertical Menus

When you first create a site structure that includes a root or top-level site, more than one Web site, and pages and additional sites that are children of the top-level site, Microsoft SharePoint Server 2010 creates two menus: a horizontal (top) menu, and a vertical (left) menu.

Horizontal and vertical menus are declared in master page markup. The following example declares a horizontal menu.

<SharePoint:AspMenu ID="GlobalNav" Runat="server"
  DataSourceID="GlobalNavDataSource"
  Orientation="Horizontal"
  StaticDisplayLevels="1"
  MaximumDynamicDisplayLevels="1" />

The vertical menu is declared similarly, but uses different properties than the horizontal menu. These properties are identical to those available on the ASP.NET Menu control.

Table 1 introduces properties included by default in master page markup for horizontal and vertical menus.

Table 1. Properties included by default in master page markup for horizontal and vertical menus

Property	Description
DataSourceID	Specifies the data source control that provides the hierarchical data for this menu. In the previous example code, the DataSourceID points to a control with the ID GlobalNavDataSource.
Orientation	Specifies whether the menu is horizontal or vertical. In the previous example code, the orientation is horizontal.
StaticDisplayLevels	Specifies the number of hierarchy levels to show in the menu at the same time. In this example, 1 is specified, indicating that the menu displays one level of hierarchy below the top-level site.
MaximumDynamicDisplayLevels	Specifies the number of levels to show in dynamic (fly-out) menus. In this example, 1 is specified, indicating that the menu item on the first level of the site hierarchy with child sites or pages displays those sites or pages in dynamict menus.

PortalSiteMapDataSource

The PortalSiteMapDataSource is a data source specific to SharePoint Server 2010 that retrieves data from the PortalSiteMapProvider object and exposes data according to the ASP.NET hierarchical data source interface. The PortalSiteMapDataSource object specifies the name of the PortalSiteMapProvider object that it uses to retrieve data through the ASP.NETSiteMapProvider property.

When the master page markup includes the DataSourceID="GlobalNavDataSource" attribute, the application returns a PortalSiteMapDataSource object.

<PublishingNavigation:PortalSiteMapDataSource ID="GlobalNavDataSource"
  Runat="server"
  SiteMapProvider="CombinedNavSiteMapProvider"
  ShowStartingNode="false"
  StartFromCurrentNode="true"
  StartingNodeOffset="0"
  TrimNonCurrentTypes="Heading"
  TreatStartingNodeAsCurrent="true" />

Table 2. Common PortalSiteMapDataSource properties

Property	Description
ShowStartingNode	Affects whether the starting node is returned by the data source. When this property is set to true, the data source returns the starting node. The menu receives the starting node, which can be the root node, and items below the starting node. When this property is set to false, the data source does not return the starting node. The menu receives only the items below the starting node.
StartFromCurrentNode	Affects where the data source starts. This property sets which section of the overall site hierarchy the data source control returns to the menu. When this property is set to true, SharePoint Server 2010 instructs the PortalSiteMapDataSource object to apply its rules for determining where it starts.
StartingNodeOffset	Gets or sets a positive or negative integer offset from the starting node that determines the top-level site hierarchy that is exposed by the DataSourceControl object. The default is 0, which indicates that the top-level site hierarchy exposed by the SiteMapDataSource object is the same as the starting node. The effect of this property is variable, undefined, and depends on site hierarchy details that are out of scope for this topic.
TrimNonCurrentTypes	Enables context-based node trimming and type-based node trimming. In this example, TrimNonCurrentTypes="Heading", which instructs the data source to remove any nodes of type Heading that are not directly below the current node. You can specify multiple values for this property in a comma-delimited list. Available values are defined in the NodeTypes enumeration.
TrimNonAncestorTypes	Trims any specified types that are not directly below the current site or one of its ancestors.
TrimNonAncestorDescendantTypes	Trims any nodes of specified types that are not below the current site or one of its ancestor or descendant sites.
TreatStartingNodeAsCurrent	Affects which node is treated as the current node for trimming purposes. By default, current node refers to the node representing the item that is currently being visited. When TreatStartingNodeAsCurrent is set to true, the starting node of the data source is treated as the context or trimming node.

PortalSiteMapProvider

The PortalSiteMapProvider object is the true source of hierarchical navigation data and it provides the data to the PortalSiteMapDataSource object. The PortalSiteMapProvider retrieves nodes from the Microsoft SharePoint Foundation 2010SPNavigation store. You use the SPNavigation object to create static links and groupings. After you provide static links and groupings, the application merges in dynamic items that represent Web sites and pages with the static links and groupings. SharePoint Server 2010 also applies security trimming so that users see only the navigation items to which they have permission to navigate.

Declare named providers in the application's web.config file to make them widely accessible. Declarations of the two most important PortalSiteMapProvider objects—CombinedNavSiteMapProvider and CurrentNavSiteMapProvider—are shown in the following code.

<add name="CombinedNavSiteMapProvider" description="MOSS 2007 provider for Combined navigation"
   Type="Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapProvider"
   NavigationType="Combined" EncodeOutput="true">
<add name="CurrentNavSiteMapProvider" description="MOSS 2007 provider for Current navigation"
   Type="Microsoft.SharePoint.Publishing.Navigation.PortalSiteMapProvider"
   NavigationType="Current" EncodeOutput="true" />

Note

The name of the first provider, CombinedNavSiteMapProvider, matches the value specified for the SiteMapProvider property. This indicates that a horizontal menu will be created.

Table 3 describes some of the more common PortalSiteMapProvider properties.

Table 3. Common PortalSiteMapProvider properties

Property	Description
NavigationType	Gets or sets the type of navigation for this navigation provider. Available options include Combined, Current, and Global and behave as specified by the next three properties: CombinedNavSiteMapProvider, CurrentSiteMapProvider, and CurrentSiteNavSiteMapProviderNoEncode.
CombinedNavSiteMapProvider	Gets the PortalSiteMapProvider object that is attached by default to the global navigation menu.
CurrentNavSiteMapProvider	Gets the PortalSiteMapProvider object that is attached by default to the current navigation menu or the QuickLaunch toolbar.
CurrentNavSiteMapProviderNoEncode	Gets the PortalSiteMapProvider object that is attached by default to the breadcrumb navigation. Declare this property almost identically to CurrentSiteNavSiteMapProvider, but exclude the EncodeOutput="true" attribute.
GlobalNavSiteMapProvider	Gets a PortalSiteMapProvider object with the NavigationType property set to Global.
EncodeOutput	Gets or sets whether to HTML-encode the Title property of any PortalSiteMapNode object returned by the provider. The ASP.NET menu control does not automatically HTML-encode the Title property when rendering. However, the ASP.NET SiteMapPath control does HTML-encode the Title property.
DynamicChildLimit	Gets or sets the number of dynamic child items to show at each level. Dynamic child items can be subsites (any SPWeb objects) and pages.
RequireUniqueKeysForNodes	Gets or sets whether nodes returned from the provider should each have unique values for their Key properties. To enable menu highlighting to work correctly on authored links and headings, set RequireUniqueKeysForNodes="false". This does not cause problems when attaching to an ASP.NET menu control through a data source, but for most other display controls, declare RequireUniqueKeysForNodes="true".
IncludeSubSites	Gets or sets whether this provider returns subsites.

Working with Menus and Navigation Objects in SharePoint Server 2010 (ECM)

Horizontal and Vertical Menus

PortalSiteMapDataSource

PortalSiteMapProvider

See Also

Reference

Concepts

Other Resources

Additional resources