Export (0) Print
Expand All

Adding Links to Quick Launch

Last modified: October 20, 2010

Applies to: SharePoint Foundation 2010

In this article
Navigating the Menu Structure
Adding an Item Below a Built-In Heading
Specifying a Position on the Menu
Adding a Custom Heading

On a Microsoft SharePoint Foundation website, Quick Launch is the static menu on the left side of most content pages. The SharePoint Foundation object model represents the Quick Launch menu as a hierarchy of SPNavigationNode objects, with each object representing a hypertext link on the menu.

Adding a new link to the menu is a matter of constructing an object to represent the link and then adding it in the right place in the hierarchy.

At the top level of the Quick Launch menu are the headings. You can get the collection of headings by first getting the object that is returned by the Navigation property of the website and by then getting the QuickLaunch property of that object. The QuickLaunch property returns an SPNavigationNodeCollection object that contains the set of SPNavigationNode objects that represent the headings.

SPNavigationNodeCollection ql = web.Navigation.QuickLaunch;

At the next level down are items below headings. Each SPNavigationNode object that represents a heading has a Children property that can contain a collection of nodes that represent items below a heading. If no items are below a heading, the Children property of the heading node returns an empty collection.

foreach (SPNavigationNode heading in web.Navigation.QuickLaunch)
{
    foreach (SPNavigationNode item in heading.Children)
    {

        // Do something.
    }
}

The heading and each item below it are SPNavigationNode objects that represent hypertext links. Display text for each link is encapsulated in the Title property of the object, and the link's URL is in the Url property of the object. The values for these properties are independent of the link's target. If the link points to a website and the site's title or URL changes, the title and URL in the navigation node do not automatically change also.

By default, the Quick Launch menu is configured to show only two levels. You can customize Quick Launch so that additional levels can appear on the static menu or on flyout menus. For more information, see How to: Customize the Display of Quick Launch.

To insert a link below one of the standard Quick Launch headings, such as Lists or Libraries, call the AddToQuickLaunch method. This method accepts two arguments: an SPNavigationNode object that represents the new link, and an SPQuickLaunchHeading enumeration value that specifies the heading that should receive the link.

The AddToQuickLaunch method is in the SPNavigation class, an instance of which is returned by the Navigation property of the SPWeb class.

To add an item under a built-in heading

  1. (Optional) Check for an existing link to the same target by calling the GetNodeByUrl method of the object that is returned by the website's Navigation property.

    If the website's navigation structure does not include a link that points to the URL, the GetNodeByUrl method returns null.

  2. Create a node to represent the link by calling one of the constructors for the SPNavigationNode class.

    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.

    Note 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 the Id property and the ParentId property return null.

  3. Call the AddToQuickLaunch method, passing the new node as the first argument and an SPQuickLaunchHeading enumeration value as the second argument.

    The AddToQuickLaunch method returns an initialized instance of the SPNavigationNode class. You can use this object to get and set other properties of the node. You must call the Update method after you change properties of the object.

Note Note

The quickest way to add an existing list or document library to the Quick Launch menu is to get an SPList object that represents the list or library, and then set the OnQuickLaunch property to true. An item for the list or library is automatically added below the appropriate heading. For information about Quick Launch headings, see the SPQuickLaunchHeading enumeration. If the heading does not yet appear on the Quick Launch menu, it is added.

Example

The following console application adds an item under the Lists heading in Quick Launch.

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Navigation;

namespace ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite site = new SPSite("http://localhost"))
            {
                using (SPWeb web = site.OpenWeb())
                {
                    // Get the Links list or create it if it does not exist.
                    SPList list = web.Lists.TryGetList("Links");

                    if (list == null || list.BaseTemplate != SPListTemplateType.Links)
                    {
                        // Create the list.
                        Guid listId = web.Lists.Add("Links", "Interesting hyperlinks", SPListTemplateType.Links);
                        list = web.Lists.GetList(listId, false);
                    }

                    // Check for an existing link to the list.
                    SPNavigationNode listNode = web.Navigation.GetNodeByUrl(list.DefaultViewUrl);
 
                    // No link, so create one.
                    if (listNode == null)
                    {
                        // Create the node.
                        listNode = new SPNavigationNode(list.Title, list.DefaultViewUrl);

                        // Add it to Quick Launch.
                        listNode = web.Navigation.AddToQuickLaunch(listNode, SPQuickLaunchHeading.Lists);
                    }
                }
            }
            Console.Write("\nPress ENTER to continue....");
            Console.ReadLine();
        }
    }
}

The AddToQuickLaunch method described in the previous section adds a new link as the last item below the specified heading on the Quick Launch menu. You can achieve more granular control over placement by using one of several methods in the SPNavigationNodeCollection class. The following table briefly describes these methods.

Method

Description

Add

Adds a new node after the specified node in the collection.

AddAsFirst

Adds a new node as the first node in the collection.

AddAsLast

Adds a new node as the last node in the collection.

The following procedure explains how to use the Add method to insert a link immediately after a specified item on the Quick Launch menu.

To insert a link after an existing item on the menu

  1. Get the node for the heading under which you want to place the link by calling the GetNodeById method of the SPNavigation class.

    // Get the Libraries heading.
    SPNavigationNode heading = web.Navigation.GetNodeById((int)SPQuickLaunchHeading.Documents);
    
  2. Get the node for the item after which you want to place the link by querying the collection that is returned by the Children property of the heading node.

    // If a node for Shared Documents exists, the new node will go after it.
    SPList sharedDocs = web.Lists.TryGetList("Shared Documents");
    SPNavigationNode sharedDocsNode = null;
    if (sharedDocs != null)
        sharedDocsNode = librariesHeading
            .Children
            .Cast<SPNavigationNode>()
            .FirstOrDefault(n => n.Url == sharedDocs.DefaultViewUrl);
    
  3. Construct an SPNavigationNode object to represent the new link.

    SPNavigationNode newNode = new SPNavigationNode(list.Title, list.DefaultViewUrl);
    
  4. Add the link by calling the Add method, passing the new node as the first argument and the node after which to add it as the second argument.

    newNode = heading.Children.Add(newNode, sharedDocsNode);
    
Note 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 the Id property and the ParentId property return null.

Example

The following example shows how to add a link at a specific position on the Quick Launch menu. The example is part of a larger project that uses a web-scoped Feature to create a document library named Meeting Notes. The Feature includes an event handler that implements the SPFeatureReceiver class. In the FeatureActivated method of the feature receiver, there is code for creating the Meeting Notes library and adding a link to it under the Libraries heading. If the menu has a link to the Shared Documents library, the new link is inserted immediately after it. If the menu does not have a link to Shared Documents, the code makes the link to Meeting Notes the first item below the Libraries heading.

Note Note

The example code uses several types without qualification. For the code to compile correctly, your feature receiver class must import the following namespaces:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
    // Get the website where the feature is activated.
    SPWeb web = properties.Feature.Parent as SPWeb;
    if (web == null)
        return;

    // Get the Meeting Notes document library.
    SPList meetingNotes = web.Lists.TryGetList("Meeting Notes");
    if (meetingNotes == null)
    {
        // Create the library if it does not exist.
        Guid listId = web.Lists.Add("Meeting Notes", "An archive for meeting notes.", SPListTemplateType.DocumentLibrary);
        meetingNotes = web.Lists.GetList(listId, false);
    }

    // Check for an existing Quick Launch node for Meeting Notes.
    SPNavigationNode meetingNotesNode = web.Navigation.GetNodeByUrl(meetingNotes.DefaultViewUrl);

    // If a Meeting Notes node exists on Quick Launch, nothing more to do.
    if (meetingNotesNode != null)
        return;

    // Still here, so create a node for Meeting Notes.
    meetingNotesNode = new SPNavigationNode(meetingNotes.Title, meetingNotes.DefaultViewUrl);

    // Get the Libraries heading.
    SPNavigationNode librariesHeading = web.Navigation.GetNodeById((int)SPQuickLaunchHeading.Documents);

    // If the Libraries heading does not exist or it exists but has no items below it,
    // then Meeting Notes will be the first item.
    if (librariesHeading == null || librariesHeading.Children.Count == 0)
    {
        web.Navigation.AddToQuickLaunch(meetingNotesNode, SPQuickLaunchHeading.Documents);
        return;
    }

    // The Libraries heading exists. Now check for an item linking to Shared Documents.
    // If a node for Shared Documents exists, Meeting Notes will go after it.
    SPList sharedDocs = web.Lists.TryGetList("Shared Documents");
    SPNavigationNode sharedDocsNode = null;
    if (sharedDocs != null)
        sharedDocsNode = librariesHeading
            .Children
            .Cast<SPNavigationNode>()
            .FirstOrDefault(n => n.Url == sharedDocs.DefaultViewUrl);

    // A node for Shared Documents does not exist. Make Meeting Notes the first item.
    if (sharedDocsNode == null)
    {
        librariesHeading.Children.AddAsFirst(meetingNotesNode);
        return;
    }

    // A node for Shared Documents exists. Place Meeting Notes after it.
    librariesHeading.Children.Add(meetingNotesNode, sharedDocsNode);

    web.Dispose();
}

The headings on the Quick Launch menu are SPNavigationNode objects. The collection of all headings is returned by the QuickLaunch property of the Navigation object of the website. You can add a custom heading by constructing a new navigation node and adding it to the collection by calling a method of the SPNavigationNodeCollection class, such as the AddAsLast method.

To add a custom heading to Quick Launch

  1. Construct an SPNavigationNode object to represent the navigation node for the new heading.

    string headingTitle = "Resources";
    string headingUrl = web.Navigation.Home.Url;
    SPNavigationNode heading = new SPNavigationNode(headingTitle, headingUrl);
    
  2. Get the collection of navigation nodes that is returned by the QuickLaunch property of the object that is returned by the SPWeb.Navigation property of the website.

    SPNavigationNodeCollection quickLaunch = web.Navigation.QuickLaunch;
    
  3. Add the new heading node to the collection by calling a method of the SPNavigationNodeCollection class.

    heading = quickLaunch.AddAsLast(heading);
    

    The example calls the AddAsLast method. Two other methods are available: the AddAsFirst method and the Add method.

  4. (Optional) Add items below the new heading by getting the collection that is returned by the Children property of the new heading and again calling a method of the SPNavigationNodeCollection class.

    SPNavigationNode item = new SPNavigationNode(itemTitle, itemUrl);
    item = heading.Children.AddAsLast(item);
    

Example

The following example is a console application that creates a new Quick Launch menu heading for Resources and adds an item below the new heading.

using System;
using System.Linq;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Navigation;

namespace ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite site = new SPSite("http://localhost"))
            {
                using (SPWeb web = site.OpenWeb())
                {
                    string headingTitle = "Resources";
                    string headingUrl = web.Navigation.Home.Url;
                    string itemTitle = "SharePoint Developer Center";
                    string itemUrl = "http://msdn.microsoft.com/sharepoint";

                    // Get the Quick Launch headings.
                    SPNavigationNodeCollection ql = web.Navigation.QuickLaunch;

                    // If a Resources heading exists, get it.
                    SPNavigationNode heading = ql
                        .Cast<SPNavigationNode>()
                        .FirstOrDefault(n => n.Title == headingTitle);

                    // If the Resources heading does not exist, create it.
                    if (heading == null)
                    {
                        heading = new SPNavigationNode(headingTitle, headingUrl);
                        heading = ql.AddAsLast(heading);
                    }

                    // If the heading has a SharePoint Dev Center item, get it.
                    SPNavigationNode item = heading
                        .Children
                        .Cast<SPNavigationNode>()
                        .FirstOrDefault(n => n.Url == itemUrl);

                    // If the item does not exist, create it.
                    if (item == null)
                    {
                        item = new SPNavigationNode(itemTitle, itemUrl, true);
                        item = heading.Children.AddAsLast(item);
                    }
                 }
            }
            Console.Write("\nPress ENTER to continue....");
            Console.ReadLine();
        }
    }
}
Show:
© 2014 Microsoft