SharePoint - regarding navigations

The out of the box navigation controls work for many scenarios, but what happens if they don't? What are the options available to have custom navigation in SharePoint (WSS or MOSS)? I am not just talking about look and feel, in fact I am mostly talking about functionality and controlling the HTML output that the navigation renders e.g. you want HTML DIV tags instead of tables with rows and cells, or what about UL and LI tags?

This is something that I have been meaning to write about for some time now, but have never had the chance. I have had so many folk ask how to have more control over the navigation output and so at long last I have decided to document several options. Besides the HTML output control, I have also had scenarios like "the navigation works okay, but in certain scenarios I want it to also wash the dishes, but only if the navigation node is a dishwasher". In this post you will find information on how to solve both of these types of scenarios, and therefore I cover the following options:

1. Out of the box controls with custom stylesheets (I won't cover this in much details as this has been done before)
2. 3rd party navigation controls
3. Use CSS Control Toolkit with out of the box navigation controls
4. Develop a custom navigation control which inherits from another
5. Develop a custom navigation control from scratch
6. Develop a custom navigation control which consumes a datasource control  (this one I have most detail on)

Option 1: Out of the box controls with custom stylesheets

This scenario doesn't solve either the issues described earlier, but I just wanted to make sure you were up to speed on navigation in SharePoint before you head down any of the other options. In other words....read this option for background info!

The navigation you see below was done using the out of the box ASP Tree View control with custom CSS styles. Not bad result for no code! In other words, no code development, just standard styling "stuff" in SharePoint.

I am not going to cover how this was achieved and all the various configuration options, but do recommend you read the following posts which do

Out of the box configuration options and how navigation works:

1. Navigation in MOSS explained Part 1
2. Navigation in MOSS explained Part 2

Branding the out of the box navigation:

Here you provide CSS styles for the SharePoint ASP menu control, the ASP .NET menu or ASP .NET tree controls, depending on which one of those you are using. (as a side note, the SharePoint ASP menu control inherits from the ASP .NET menu control to change some small behaviour).

Option 2: 3rd party navigation controls

You may find that purchasing a 3rd party navigation control will be a better option for you if you are looking for a "fancy" or WOW user experience, without having to worry about developing or supporting it yourself. What you are really looking for here is a control which can be used to bind to an ASP .NET navigation data source provider, like the ASP .NET menu, ASP .NET tree and SharePoint ASP menu controls do. In other words, you want it to work just like they do, and simply replace one of the out of the box controls with a 3rd party one.

One such company that provides rich controls is Telerik.

The above screen shot is their RadMenu control (showing various style options). They even have documentation on how to get this control working in SharePoint.

Option 3: Use CSS Control Toolkit with out of the box navigation controls

The out of the box navigation controls emit HTML which is full of tables, rows and cells. In some scenarios customers have requested that instead of HTML tables, they would like to have DIV tags (or any other set of HTML tags). One way of achieving this is through the CSS Control Toolkit. The toolkit consists of control adapters, which are little pieces of logic that you add to your web site to effectively "adapt" an ASP.NET control to render the HTML you prefer. The ASP.NET 2.0 CSS Friendly Control Adapters kit provides pre-built control adapters that you can easily use to generate CSS friendly markup from some of the more commonly used ASP.NET controls.

This will work with ASP navigation and SharePoint navigation controls. Instead of me documenting the steps to get this working in a SharePoint environment, let me rather point you to a blog entry by the Mossman titled "CSS Friendly Control Adapters in SharePoint 2007 (A Walk-Through)", which has the steps documented for you already.

NOTE: when I tried this for demonstration purposes it worked well, except for the fact that it also changed the navigation on the internal SharePoint application pages e.g. site settings etc, and this caused weird behaviour on those pages. Therefore, you might want to modify the source code of the CSS Control Adapter for the menu control to only work on specific scenarios so that it doesn't effect your application pages. The source code for the toolkit is available on CodePlex.

Option 4: Develop a custom navigation control which inherits from another

You develop a custom ASP .NET navigation control which inherits from an existing control i.e. ASP .NET menu, ASP .NET tree or SharePoint ASP menu control. You then have the option of overriding specific functionality to get what you want (for formatting and perhaps functionality reasons). This is exactly what the SharePoint product team did when developing the SharePoint ASP menu, it inherits from ASP .NET menu and changes certain functionality. A good example of how to do this, is found by downloading the source code for the SharePoint ASP menu which the SharePoint team have released here.

NOTE: you may not be able to override all functionality, you will need to play with this to see if you can achieve your goals, otherwise you will need to use one of the other custom navigation options.

Option 5: Develop a custom navigation control from scratch

The next 2 options cover the scenario where you want to control the HTML output whether it be DIV, Table or any another HTML tags. It also covers the dishwasher scenario I mentioned at the top of this article. In the dishwasher scenario you want custom logic in deciding which nodes to render in your navigation, beyond the standard SharePoint logic and rules e.g. only render navigation nodes where the 1st letter of the node, is the same as the first letter of the name of the person viewing the page. Okay, not a great real world example, but hopefully you get the idea.

In this option (option 5), you develop a navigation control in the same way as you develop any other ASP .Net server control, but you call the SharePoint API to get back the navigation nodes required to render your navigation.

You may have some type of recursive function which starts from the current node (current site e.g. SPWeb object) and loops through all child and sibling nodes to render the navigation. Those developers who come from a Microsoft Content Management Server (MCMS) 2002 background will understand this model, because this is essentially the same as looping through channel and posting objects to render the navigation required.

Note: The out of the box navigation controls in SharePoint do not work in this way, they are true ASP .NET navigation controls which get there data (navigation nodes) from a data source control.

Developing a control which does not need a data source control has some draw backs.  You need to code various configuration options into your control if you want SharePoint configuration to still be used to define which nodes are rendered e.g. show pages or not, start from the current node, ignore headings, ignore links. I.e. the options which are available through the SharePoint UI to change the navigation.

So where do I start?

1. Firstly, you need to be an ASP .Net web control developer who knows how to; develop composite controls by overriding the CreateChildControls method or rendering your own HTML in the render method of the control. If you don't have a clue what I am talking about here.....find a web control developer.
2. Get familiar which the SharePoint API, specifically the SPWeb and PortalSiteMapNode and class.
3. Read and digest "Increased performance for MOSS apps using the PortalSiteMapProvider" - this will give you an idea of how you access the nodes in the hierarchy so that you can render them.

Sample:

Once again, instead of doing all the hard work here, I am going to point you to a sample developed by Stephen Huen. Download it and take a look at the good sample.

Option 6: Develop a custom navigation control which consumes a datasource control

Like option 5, this allows for complete HTML output control and covers the dishwasher scenario too. However, the implementation is different to option 5.

The difference in this model is that the data source (navigation nodes) are "given" to you by the data source control. You don't need code to get the navigation items and you don't need to worry about showing or hidding navigation items based on navigation configured through the SharePoint UI. The data source will only give you the nodes which you are supposed to render based on the SharePoint navigation configured through the UI. Of course you could still add your custom logic beyond the standard SharePoint logic, which would be one of the reasons for developing this control in the first place.

At a high-level you would do the following to develop this control:

1. Create a class which Inherits from HierarchicalDataBoundControl
2. Override the PerformDataBinding method
3. Override Render method
4. Deploy Control into GAC or into local \BIN folder of web application (if local bin, you MUST change trust level in web.config to WSS_Medium or Full)

Instead of walking through every line of code which would make up such a control, I have put together a sample control, which has loads of comments included to help you understand the logic. However, let me give you a broad overview anyway.

Overview of the Sample

The requirement is to have complete control of the rendered HTML for the navigation e.g. nodes represented as a LI tags inside a UL tag, and CSS styles would be used to show navigation level 1, 2, 3 etc. The sample takes the navigation nodes from the data source control and creates an XML document which represents the navigation (this is done in the PerformDataBinding method). Each navigation node in the XML document is represented as a <node> element with attributes e.g. title, url and the navigation hierachy is represented by the node element hierachy i.e. a <node> element can have sibling and child <node> elements. All that is left to do is render your HTML in the Render method, and it is here where you can do what you like.

If a node is current, then we set the attribute "selected" in the XML document to true.

Three important points to be aware of:

1. When a page with the navigation control on it performs a postback, the PerformDataBinding method is NOT called. Therefore, on postback you will get an empty navigation control. This is "by design" and I didn't figure out a way to force PerformDataBinding to execute. Instead, I saved the XML document which is created in the PerformDataBinding method into viewstate, so that when a postback is performed, we still have the XML from which to work. I also looked at the size of the viewstate produced by navigation control compared to the out of the box ASP Menu, ASP Tree and SharePoint menu controls and it was smaller (I didn't test all cases, but tried various with a fair amount of navigation items).
2. If you use this sample and get no navigation nodes shown / returned, it is probably because your navigation assembly is not in the GAC. If it is in the local bin folder for the web application you need to change the default trust level in web.config from WSS_Minimal to WSS_Medium or Full. I am not going into code access security in this post, which is what this is all about.
3. In the sample, I have left the render method "empty", so this is where you need to put in your own rendering logic. At the moment it will just render the XML inside the XML document (see screen shot below). You could use XSLT transformation, or iterate through the XML document and render as appropriate. Your call.

If you add the sample control “as is” to a SharePoint site, you get the following:

Standard Control

Sample Control (render raw XML)

Problem
A SiteMapPath control in asp.net reads its data directly from the SiteMapProvider which makes setting the ShowRootNode property impossible.
This maybe something you´re used to from menu controls and such that uses a SiteMapDataSource. 

Example
Home / Site 1 / SubSite 1 / Page below subsite 1

Here one might want to hide “Home” (which is the rootnode of the provider). 

Solution
You can, through code, check if the node that is to be rendered is a root node and if such hide it, as this example code shows:

Listen to the event when the nodes are created (ItemCreated).

    <asp:SiteMapPath ID="siteMapPath" runat="server"
      Pathseparator="/"
      OnItemCreated="SiteMapPath_ItemCreated">
     
    <NodeTemplate>
      <a href='<%# Eval("url") %>'><%# Eval("title") %></a>
    </NodeTemplate>
   
    <CurrentNodeTemplate>
      <%# Eval("title") %>
    </CurrentNodeTemplate>   
   
    </asp:SiteMapPath>

Check if the node is a rootnode and hide it. (also hide the first separator, it won´t be nice to start of with a slash).

protected void SiteMapPath_ItemCreated(object sender, SiteMapNodeItemEventArgs e)
{
    if (e.Item.ItemType == SiteMapNodeItemType.Root || (e.Item.ItemType == SiteMapNodeItemType.PathSeparator && e.Item.ItemIndex == 1))
    {
      e.Item.Visible = false;
    }
}

After this “fix” the rootnode is hidden in the breadcrumb.

Example
Site 1 / SubSite 1 / Page below subsite 1

First thing I did was creating a set of sites and sub sites under the site Sites of type Site Directory with the following structure:

site1
          site1sub1
                  site1sub1subA
                  site1sub1subB
          site1sub2
                  site1sub2subA
                  site1sub2subB
site2
          site2sub1
                  site2sub1subA
                  site2sub1subB
          site2sub2
                  site2sub2subA
                  site2sub2subB

This results in the following homepage navigation:

As you can see, two levels of navigation are displayed.

Navigation Inheritance

When a site is created you are prompted with the following option:

The default setting for this option is Yes. I created site1 and site2 using the Yes setting, and a site3 using the No setting. The results are as follows:

For site2 (use the top link bar from the parent site):

For site3 (don’t use the top link bar from the parent site):

I can see no difference between the two options, both shows their complete path in the breadcrumb bar:

For site3 I actually expected to see:

Another strange thing is that I didn’t find an option in the UI with the same phrasing to modify this setting after initial creation of the site. This option can be set in a working way however, keep on reading!

Site navigation

If you navigate to Sites you get the following navigation:

So all sub sites are displayed, with one level of the sub-sub sites.

If you navigate from here to site2 you get the following navigation:

This is a different navigation. The current site (site2) is displayed with one level of children (site2sub1, site2sub2), and sites at the same level (site1, site2).

The question now is: what configures the navigation? If you go to Site Actions >Site Settings >Modify Navigation you get to the Site Navigation Settings.

The Site Navigation Settings screen looks as follows:

This screen asks for some experiments!

Site Navigation Settings

The Site Navigation Settings screen gives us some configuration options on how navigation works on a site. Lets start with the following options:

Global Navigation: Use global navigation of the parent site or of this site.

Current Navigation: Use navigation items of the parent site or of this site. If this site is selected, you can enable to show siblings of this site in the current navigation.

For the site site1sub1 we go through the different possibilities.

Global navigation: global navigation of parent

There are two major requirements:

1. All site collections must be on the same farm. They can be part of different applications, or part of the same application, but must be on the same farm.
2. All webs implementing this navigator must have the Office SharePoint Server Publishing feature activated.

And, there are three major steps for installation:

1. Add the DLL to the GAC
2. Add the navigation provider to the web.config
3. Modify the master page to use SharedNavigationProvider

1. Add the DLL to the GAC

• I added a small .bat file, AddToGAC.bat, to the root of the project that does just that.
• I am assuming you have gacutil.exe in c:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\. If not, you should find a way to get it. (For more info about gacutil, please see: http://msdn.microsoft.com/en-us/library/ex0ss12c(VS.85).aspx).
• You must repeat this step on all front web servers.

2. Add the Navigation Provider to the web.config

• Locate the web.config of your site collection (actually of your web application) and add the following provider entry:
Collapse | Copy Code

<!-- ... -->
<system.web>
    <siteMap …>
        <providers>
        <!-- ... -->
        <add name="SharedNavigationProvider" 
           SourceSite="http://SourceSiteCollection" 
           NavigationType="Global" EncodeOutput="true" 
           type="DataQ.SharePoint.Providers.SharedNavigationProvider, 
                 SharedNavigationProvider, Version=1.0.0.0, 
                 Culture=neutral, PublicKeyToken=fc448b9e121af773" />
        </providers>
<!-- ... -->

• Set the SourceSite parameter to be the URL of the source site collection from where you want to borrow the navigation.
• Repeat this step on all front web servers, if you have more than one.

3. Modify the Master Page to Use SharedNavigationProvider

Your master page needs to be modified to use the provider. You can do this in more than one way. You may use SharePoint Designer, or you may download the file, modify it, then upload, publish, and approve it. I don't think it is necessary to elaborate on that, but if you feel I should, drop me a message, and I'll do.

I will describe here what you need to change once you have the default.master (or whatever.master page you have set for your site) file opened.

1. Be sure you keep a backup copy of the master page you are going to change.
2. Be sure you are doing 1.
3. Open the master page in your HTML editor of choice.
4. Locate this control: <SharePoint:DelegateControl runat="server" ControlId="TopNavigationDataSource">, and underneath it, place this control:
Collapse | Copy Code

<asp:SiteMapDataSource 
    ShowStartingNode="False"
    SiteMapProvider="SharedNavigationProvider"
    id="topSiteMap2"
    runat="server"/>

5. Locate this control: <SharePoint:AspMenu ID="TopNavigationMenu" ….. You should find it above the control we modified in 4.

Change the attributes DataSourceID to topSiteMap2 and StaticDisplayLevels to 1:




DataSourceID="topSiteMap2"
StaticDisplayLevels="1"

6. If you use the out-of-the-box default.master page, all these changes should look like this:



<SharePoint:AspMenu
      ID="TopNavigationMenu"
      Runat="server"
      DataSourceID="topSiteMap2"
      EnableViewState="false"
      AccessKey="<%$Resources:wss,navigation_accesskey%>"
      Orientation="Horizontal"
      StaticDisplayLevels="1"
      MaximumDynamicDisplayLevels="1"
      DynamicHorizontalOffset="2"
      StaticPopoutImageUrl="/_layouts/images/menudark.gif"
      StaticPopoutImageTextFormatString=""
      DynamicHoverStyle-BackColor="#CBE3F0"
      SkipLinkText=""
      StaticSubMenuIndent="0"
      CssClass="ms-topNavContainer">
        <StaticMenuStyle/>
        <StaticMenuItemStyle CssClass="ms-topnav" ItemSpacing="0px"/>
        <StaticSelectedStyle CssClass="ms-topnavselected" />
        <StaticHoverStyle CssClass="ms-topNavHover" />
        <DynamicMenuStyle  BackColor="#F2F3F4" 
          BorderColor="#A7B4CE" BorderWidth="1px"/>
        <DynamicMenuItemStyle CssClass="ms-topNavFlyOuts"/>
        <DynamicHoverStyle CssClass="ms-topNavFlyOutsHover"/>
        <DynamicSelectedStyle CssClass="ms-topNavFlyOutsSelected"/>
    </SharePoint:AspMenu>
        
<SharePoint:DelegateControl runat="server" 
          ControlId="TopNavigationDataSource">
    <Template_Controls>
        <asp:SiteMapDataSource
          ShowStartingNode="False"
          SiteMapProvider="SPNavigationProvider"
          id="topSiteMap"
          runat="server"
          StartingNodeUrl="sid:1002"/>
    </Template_Controls>
</SharePoint:DelegateControl>

<asp:SiteMapDataSource 
  ShowStartingNode="False"
  SiteMapProvider="SharedNavigationProvider"
  id="topSiteMap2"
  runat="server"/>

7. When you upload the modified master page, don’t forget there are three important steps to follow:
   1. Check in
   2. Publish as a Major Version
   3. Approve the new master page