Working with Menus and Navigation Objects

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, Office SharePoint Server 2007 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 from the horizontal menu. These properties are identical to those available on the ASP.NET 2.0 Menu control.

The following table introduces properties included by default in master page markup for both 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 fly-out menus.

PortalSiteMapDataSource

The PortalSiteMapDataSource is a data source specific to Office SharePoint Server 2007 that retrieves data from the PortalSiteMapProvider object and exposes data according to the ASP.NET 2.0 hierarchical data source interface. The PortalSiteMapDataSource object specifies the name of the PortalSiteMapProvider object it uses to retrieve data through the ASP.NET 2.0 SiteMapProvider 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" />
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. That is, 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, Office SharePoint Server 2007 instructs the PortalSiteMapDataSource object to apply its rules for determining where it should be starting.

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

Allows context-based 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 Windows SharePoint Services 3.0 SPNavigation 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. Office SharePoint Server 2007 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 CurrentSiteNavSiteMapProvider—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.

The following table describes some of the more 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.

CurrentSiteNavSiteMapProvider

Gets the PortalSiteMapProvider object that is attached by default to the current navigation menu or the QuickLaunch toolbar.

CurrentSiteNavSiteMapProviderNoEncode

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 2.0 menu control does not automatically HTML-encode the Title property when rendering. However, the ASP.NET 2.0 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 2.0 menu control through a data source, but for most other display controls, declare RequireUniqueKeysForNodes="true".

IncludeSubSites

Gets or sets whether this provider returns subsites.

See Also

Reference

Microsoft.SharePoint.Publishing.Navigation
Microsoft.SharePoint.Navigation

Other Resources

How to: Customize Navigation
Modifying Navigation Settings through the UI
Customizing Navigation Controls and Providers