Share via


Adding Links to the Top Link Bar

Applies to: SharePoint Foundation 2010

On a Microsoft SharePoint Foundation website, the top link bar is the tabbed strip that appears just below the website's title and description. The SharePoint Foundation object model represents the navigational structure of the top link bar as a collection of SPNavigationNode objects. You add links by adding SPNavigationNode objects to the top link bar's collection.

A website's top link bar is represented by an instance of the SPNavigationNodeCollection class. You get the collection by accessing the website's SPWeb.Navigation property, which returns an SPNavigation object, and then by accessing that object's TopNavigationBar property.

SPNavigationNodeCollection topnav = web.Navigation.TopNavigationBar;
Dim topnav As SPNavigationNodeCollection = web.Navigation.TopNavigationBar

Warning

If a website is configured to use the top link bar from its parent site, its SPWeb.Navigation.TopNavigationBar property returns null.

After you have a collection, you can construct an SPNavigationNode object to represent the new link and then call a method of the SPNavigationNodeCollection class to add the node to the top link bar.

  1. Check the value of the SPWeb.Navigation.UseShared property to be sure that the website has its own top link bar and is not inheriting links from a parent site.

    If UseShared returns false, the website has its own top link bar and you can add to it. If the property returns true, the website is using its parent site's top link bar. In this case, you can add the link to the parent site's top link bar, or you might instead choose to place the link on the child site's Quick Launch menu.

  2. Check for a duplicate link.

    One way to check is to call the SPWeb.Navigation.GetNodeByUrl method, passing the proposed link's URL as an argument. If a link with that URL is not found, the GetNodeByUrl method returns null.

    If a link is found, the method returns an SPNavigationNode object. However, the existing link could be on the Quick Launch menu rather than on the top link bar. To verify whether an existing link belongs to the top link bar, check the ParentId property of the node that is returned. The Id of the top link bar is always 1002.

  3. If the top link bar does not already have the link, use one of the constructors for the SPNavigationNode class to create a navigation node for it.

    The class has two constructors:

    • The first constructor accepts two arguments: a string that contains display text for the link, and another string that contains the URL that the link should resolve. Use this constructor only for internal links—links to content in the same site collection. The URL should be server-relative.

    • The second constructor accepts three arguments. The first two arguments are the same as for the other constructor. The third argument is a boolean value that indicates whether the link is external or internal. Pass true for a link to an external website, and pass an absolute URL in the second argument. If the link is internal, pass false and a server-relative URL.

  4. Get a reference to the SPNavigationNodeCollection object that represents the top link bar by getting the value of the SPWeb.Navigation.TopNavigationBar property.

  5. Call a method of the SPNavigationNodeCollection class to add the node to the collection.

    To make the node the first node on the bar, call the AddAsFirst method. To make it the last node, call the AddAsLast method. To insert it after another node, call the Add method.

Note

An SPNavigationNode object is not completely initialized until it is added to a collection. If the object is not yet a member of a collection, read-only properties such as Id and ParentId return null.

Example

The console application in the following example iterates over the collection of websites in a site collection, adding a link to each website on the top link bar for the collection's root website. Before adding a link, the application checks for an existing link.

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())
            {
                if (web.Navigation.UseShared) 
                    return; 

                // Get the top link bar.
                SPNavigationNodeCollection topnav = web.Navigation.TopNavigationBar;

                // Iterate over the collection of subsites.
                foreach (SPWeb subweb in web.Webs)
                {
                    // Check for an existing link.
                    SPNavigationNode node = web.Navigation.GetNodeByUrl(subweb.ServerRelativeUrl);
                    if (node == null || node.ParentId != 1002)
                    {
                        // No link, so add one.

                        // Truncate a long title.
                        string linkTitle = subweb.Title;
                        if (linkTitle.Length > 15)
                            linkTitle = linkTitle.Substring(0, 12) + "...";

                        // Create the link.
                        node = new SPNavigationNode(linkTitle, subweb.ServerRelativeUrl);

                        // Add it to the top link bar.
                        node = topnav.AddAsLast(node);
                    }
                    subweb.Dispose();
                }
            }
            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()

                If web.Navigation.UseShared Then
                    Return
                End If

                ' Get the top link bar.
                Dim topnav As SPNavigationNodeCollection = web.Navigation.TopNavigationBar

                ' Iterate over the collection of subsites.
                For Each subweb As SPWeb In web.Webs
                    ' Check for an existing link.
                    Dim node As SPNavigationNode = web.Navigation.GetNodeByUrl(subweb.ServerRelativeUrl)
                    If node Is Nothing OrElse node.ParentId <> 1002 Then

                        ' No link, so add one.

                        ' Truncate a long title.
                        Dim linkTitle As String = subweb.Title
                        If linkTitle.Length > 15 Then
                            linkTitle = linkTitle.Substring(0, 12) + "..."
                        End If

                        ' Create the link.
                        node = New SPNavigationNode(linkTitle, subweb.ServerRelativeUrl)

                        ' Add it to the top link bar.
                        node = topnav.AddAsLast(node)
                    End If
                    subweb.Dispose()
                Next

            End Using
        End Using

        Console.Write(vbCrLf & "Press ENTER to continue....")
        Console.Read()
    End Sub

End Module

See Also

Tasks

How to: Add a Subsite to the Top Link Bar or Quick Launch Menu

Concepts

How to: Share the Top Link Bar Between Sites

How to: Customize the Display of the Top Link Bar