15JUN 2013

SP 2013: Extending the SuiteBarDelegateControl by adding the Title Breadcrumb control


Posted by Tobias Zimmergren

Author: Tobias Zimmergren
http://www.zimmergren.net | http://www.tozit.com | @zimmergren

Introduction

In one of my previous articles where we investigated some of the new and awesome delegate controls in SharePoint 2013. It walks you through some of the interesting DelegateControl additions that I was playing around with. On top of that I got a comment about how you could extend it further by adding the current site title in the Suite bar:

image

Sure enough, I took a dive into the Seattle.master to take a look at how the title is rendered and found the control called SPTitleBreadcrumb. This is the control that is responsible for rendering the default out of the box title in a normal SharePoint team site like this:

image

So to follow the question through and provide an answer to get you started, we’ll take a quick look on how we can build further on our old sample from the previous blog post and add the site title (including or excluding breadcrumb-functionality) to the Suite bar.

Investigating the out of the box Seattle.master

In the OOTB Seattle.master, the title is rendered using the following code snippet:

<h1 id="pageTitle" class="ms-core-pageTitle">
  <SharePoint:AjaxDelta id="DeltaPlaceHolderPageTitleInTitleArea" runat="server">
    <asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" runat="server">
      <SharePoint:SPTitleBreadcrumb
              runat="server"
              RenderCurrentNodeAsLink="true"
                  SiteMapProvider="SPContentMapProvider"
              CentralAdminSiteMapProvider="SPXmlAdminContentMapProvider">
        <PATHSEPARATORTEMPLATE>
          <SharePoint:ClusteredDirectionalSeparatorArrow runat="server" />
        </PATHSEPARATORTEMPLATE>
      </SharePoint:SPTitleBreadcrumb>
    </asp:ContentPlaceHolder>
  </SharePoint:AjaxDelta>
  <SharePoint:AjaxDelta BlockElement="true" id="DeltaPlaceHolderPageDescription" CssClass="ms-displayInlineBlock ms-normalWrap" runat="server">
    <a href="javascript:;" id="ms-pageDescriptionDiv" style="display:none;">
      <span id="ms-pageDescriptionImage">&#160;</span>
    </a>
    <span class="ms-accessible" id="ms-pageDescription">
      <asp:ContentPlaceHolder id="PlaceHolderPageDescription" runat="server" />
    </span>
    <SharePoint:ScriptBlock runat="server">
      _spBodyOnLoadFunctionNames.push("setupPageDescriptionCallout");
    </SharePoint:ScriptBlock>
  </SharePoint:AjaxDelta>
</h1>

What we can see in this file is that there’s a lot of action going on to simply render the title (or title + breadcrumb). You can play around with this in tons of ways, both server-side and client side. In this article we’ll take a look at how we can extend the Suite bar delegate control from my previous article in order to – using server side code – modify the title and breadcrumb and move it around a bit.

Should you want to get the title using jQuery or client side object models, that works fine too. But we can save that for another post.

Adding the Title Breadcrumb to the Suite bar

I’m going to make this short and easy. The very first thing you should do is head on over to my previous article “Some new DelegateControl additions to the SharePoint 2013 master pages” and take a look at the “SuiteBarBrandingDelegate Delegate Control” section and make sure you’ve got that covered.

Once you’ve setup like that, here’s some simple additional tweaks you can add to your Delegate Control in order for the breadcrumb to be displayed in the top row of SharePoint. Modify the content of the “SuiteBarBrandingDelegate.ascx.cx” (the file in my previous sample is named like that, in your case it may differ) to now look something like this:

protected void Page_Load(object sender, EventArgs e)
{
    // Register any custom CSS we may need to inject, unless we've added it previously through the masterpage or another delegate control...
    Controls.Add(new CssRegistration { Name = "/_layouts/15/Zimmergren.DelegateControls/Styles.css", ID = "CssReg_SuiteBarBrandingDelegate", After = "corev5.css" });

    BrandingTextControl.Controls.Add(new Literal
    {
        Text = string.Format("<a href='{0}'><img src='{1}' alt='{2}' /></a>",
            SPContext.Current.Site.Url,
            "/_layouts/15/images/Zimmergren.DelegateControls/tozit36light.png",
            SPContext.Current.Site.RootWeb.Title)
    });

    // Create a new Title Breadcrumb Control
    SPTitleBreadcrumb titleBc = new SPTitleBreadcrumb();
    titleBc.RenderCurrentNodeAsLink = true;
    titleBc.SiteMapProvider = "SPContentMapProvider";
    titleBc.CentralAdminSiteMapProvider = "SPXmlAdminContentMapProvider";
    titleBc.CssClass = "suitebar-titlebreadcrumb";
    titleBc.DefaultParentLevelsDisplayed = 5;

    // Add the Title Breadcrumb Control
    BrandingTextControl.Controls.Add(titleBc);
}

As an indication, the end-result might look something like this when you’re done. What we’ve done is simply copied the logic from the Seattle.master into the code behind file of our delegate control and set the “DefaultParentLevelsDisplayed” to a higher number than 0 so it’ll render the actual breadcrumb. By setting this value to 0, only the title will be displayed.

image

Then if you want to hide the default title, you can do that by using this small CSS snippet:

#pageTitle 
{
    display: none;
}

And it’s gone:

image

From there you should be able to take it onwards and upwards in term of the styling. I haven’t really put any effort into making it pretty here :-)

Summary

With these small additions and changes to my original code samples you can make the title bar, including or excluding the breadcrumb, appear in the top bar instead of in the default title-area.

Additional important comments:

You may need to consider ensuring that the Site Map datasource is available on every page, including system pages for example. If it isn’t or you land on a page that don’t want to render your breadcrumb/title, it may not be able to properly render your navigation as you would expect it to. However that’s something to look into further from that point.

For example, by default the “Site Content” link will not render the full breadcrumb properly, but rather just say “Home”. In order to fix smaller issues like that, we can further extend the code logic a few lines and take care of those bits.

My recommendation:

Always make sure you consider the approach you take for any type of customization and development. For this specific case, we’ve already used some code-behind to display our logo in the top left corner, so we’ve just built some additional sample code on top of that to render the breadcrumbs. However should we only want to do that and not move further onwards with the logic from here – I would most likely suggest you do this using jQuery/CSOM instead to be “Office 365 compliant” and keeping your customizations to a minimum.

Hope you enjoyed this small tweak. And keep in mind: Recommendations going forward (however hard it’ll be to conform to them) are to keep customizations to a minimum!

Cheers, Tob.

  • rickard svensson

    nice tricks to get better navigation. having the entire h1-tag as the bread crumb is making me sad, so this looks much more better. keep the tips coming:)

    • http://www.zimmergren.net/ Tobias Zimmergren

      Cheers.

  • Martin Hatch

    great place to put the breadcrumb :) nice idea!

    • http://www.zimmergren.net/ Tobias Zimmergren

      Cheers Martin!
      Got the idea from “Sind” as seen in the start of the post there, and it really does look pretty nice.

  • Paul

    Good idea.

    Additionally can you please post /Zimmergren.DelegateControls/Styles.css contents for full reference?

    • http://www.zimmergren.net/ Tobias Zimmergren

      Hi Paul,
      I don’t have the project available from where I am at the moment, but it’s just some simple minor css tweaks to get things in the right place.

      Cheers,
      Tob.

  • Shailendra

    Hi Tobias, I tried this. But for me it works if MDS is disabled. i.e. it works if site url is http://sitename/SitePages/Home.aspx and if site url is http://sitename /_layouts/15/start.aspx#/SitePages/Home.aspx it given an error
    401 UNAUTHORIZED.
    Any workaround?

    • Kristin

      This has to do with the minimal download strategy being enabled. I read on another site to add the SharePoint:AjaxDelta tag to the user control, but I have yet to get it working even with the Ajax Delta control.

  • Arwena Verdier

    Hello Tobias, I have my breadcrumb works fine on my environment against it takes into account the name of the page on the test environment,
    do you have any idea why?

  • Pingback: An interesting year is coming to an end, thank you 2013 – let’s embrace 2014! | Tobias Zimmergren's thoughts on development