Top Navigation Example

Understand the basic HTML structure for top navigation

The basic structure for the top navigation is very much like what you will see on any BootStrap page. Most of the work in dealing with SharePoint's unique way of rendering navigation has been taken care of for you by ReSPondev CSS and code.

Here's an example taken from the BSSeattle HTML Masterpage:

<nav class="navbar navbar-expand-lg navbar-toggleable-md navbar-dark bg-dark">
    <!-- fixed-top -->
    <button class="navbar-toggler d-lg-none navbar-toggler-right" type="button" data-toggle="collapse" data-target="#top-nav-crush" aria-controls="top-nav-crush" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon">
        </span>
    </button>
    <a class="navbar-brand" href="http://liquidmercurysolutions.com/apps/respondev">Re<u>SP</u>ondev&trade;</a>
    <div class="collapse navbar-collapse" id="top-nav-crush">
        <div id="top-nav" class="">
            <!-- DeltaTopNavigation and related placeholder control go here ... -->
        </div>
        <!-- top-nav -->
        <div id="searchBox" class="d-inline-block"><!-- was class="ms-tableCell ms-verticalAlignTop" -->
            <!-- PlaceHolderSearchArea and related delegate controls go here ... -->
        </div>
        <!-- searchBox -->
        <div id="groupActionsBox" class="d-inline-block"><!-- class="ms-tableCell ms-verticalAlignTop" -->
            <!-- DeltaPlaceHolderGroupActionsArea and related controls go here ... -->
        </div>
        <!-- groupActionsBox -->
    </div>
    <!-- top-nav-target -->
</nav>

Configure the Site Map Data Source

Note that top navigation data sources appear to be heavily cached in Office 365 and may be attached to some kind of timer job, especially if you're using managed navigation. So, if you make a change to top navigation, even a change of the masterpage itself, it may not appear to update for quite a while.

For SiteMapProvider="..." Use:

  • "GlobalNavigationSwitchableProvider" when you are using managed navigation and it may alternate based on the settings of different sub-sites
  • "NavigationPortalSiteMapProvider" on sites with Publishing Page based navigation where you want the contents of Pages library to appear in the navigation. We observed that managed navigation nodes will dissappear in this case, and you will see structural navigation *only* from the Publishing Model's P.O.V.
  • "SPNavigationProvider" Used in default navigation for Seattle.master Seems to mostly respect managed navigation. Can be used on system pages and other areas where publishing based providers like "NavigationPortalSiteMapProvider" do not work as intended.
  • "CombinedNavSiteMapProvider" in some special cases StartingNodeUrl can be left out when using CombinedNavSiteMapProvider

The PublishingNavigation:PortalSiteMapDataSource control is known to produce odd results on some kinds of pages, so generally we don't make use of it and instead stick to ASP SiteMapDataSource control instead.

This peice of code goes into the HTML layout page, within the Template_Controls element of the TopNavigationDataSource delegate control. It's purpose is to set up the site map data source. It is basically a standard SharePoint control, and we haven't done anything much special to it other than to experiment with different settings until we got a desireable configuration. ReSPondev CSS and scripts are designed to adapt to the HTML output that SharePoint produces on the page.

<!--SPM:<asp:SiteMapDataSource
    id="topSiteMap"
    SiteMapProvider="NavigationPortalSiteMapProvider"
    ShowStartingNode="True"
    StartingNodeOffset="0"
    StartingNodeUrl="sid:1002"
    runat="server"
/>--> 

Configure the AspMenu control

The next step would be to configure the menu control, which can be found inside the ContentPlaceHolder control with id "PlaceHolderTopNavBar" and does not have any Template_Controls section at all. Replace the existing control with the following:

<!--MS:<SharePoint:AspMenu
    ID="TopNavigationMenu"
    Runat="server"
    EnableViewState="false"
    DataSourceID="topSiteMap"
    AccessKey="&#60;%$Resources:wss,navigation_accesskey%&#62;"
    UseSimpleRendering="true"
    UseSeparateCss="true"
    CssClass="navbar-nav mr-auto allow-wrap d-inline-block"
    Orientation="Horizontal"
    AdjustForShowStartingNode="true"
    StaticDisplayLevels="1"
    MaximumDynamicDisplayLevels="3"
    RenderingMode="List"
    SkipLinkText="">-->
<!--ME:</SharePoint:AspMenu>-->

AdjustForShowStartingNode should generally be "true" just in case you are using a data source and provider that do not correctly report it, but as MS points out the default value is false and in many cases this can be turned off.

You can add "hide-home-link" to CssClass to have ReSPondev CSS hide the first navigation link; this is useful if for whatever reason you can't get the desired effect using ShowStartingNode in the SiteMapDataSource above.

StaticDisplayLevels should be "1" when using SiteMapProvider "GlobalNavigationSwitchableProvider"; in some cases, we've seen that other providers may require a setting of "2" because they consider the home page link to be the first level.

MaximumDynamicDisplayLevels can be however many layers of dropdown menu you want, but in general it is considered impractical UI to have a value greater than 2.

UseSimpleRendering should be "true" in order to be compatible with ReSPondev CSS styles and JS code that converts the menu to pure-bootstrap. We have experimented with "false" and while we made some improvements to make it readable, there is still work to be done before it will display properly upon being fed through the public proxy. The dropdowns/flyouts do work on private/intranet site, but we can't promise they will behave in the intended way, and the Edit Links buttons do not appear at all.

RenderingMode should always be "List" as we've never had any use to develop support for the other option.