This was a triumph.
I'm making a note here: HUGE SUCCESS.

Search This Blog

Thursday, January 23, 2014

How to get a term-driven breadcrumb trail with full hierarchy in SharePoint 2013

On the 6th of May, 2013, I had asked a question on Stack Overflow on how one could create a term-driven hierarchical breadcrumb trail in SharePoint 2013. Alas, never really got an answer that suited my needs.

Yesterday, I suddenly had the idea to just try and find a solution with JavaScript. The idea was to loop through the subsite navigation and see which list item resembled the current page, then find all the parent elements of that list item and fetch their values. And in case I was on a page that wasn't part of a subsite (but rather just a page at the top site collection), I would just fetch the title of the page and add that to the breadcrumb trail.

Here's a screenshot of how my breadcrumb looked like earlier:

And here's a screenshot of how it looks like now:

Pretty nice, huh?

Let's just get started, I'll give you the code.

The code

// Just add the following line.
   "~sitecollection/Style Library/Scripts/jquery.SPServices-2013.01.js");

var siteCollection = "Your site collection name";
var siteCollectionUrl = "/";     
var pageName; 
var subsite;
// Fetch the name of the subsite you're currently on.
    operation: "SiteDataGetWeb",
    async: false,
  completefunc: function (xData, Status) {
   subsite = $(xData.responseXML).SPFilterNode("Title").text();
// Fetch the url of the subsite you're currently on.
var subsiteUrl = $().SPServices.SPGetCurrentSite();
// Fetch the title of the page, remove a piece of text from the title
// (in my case, "Pages - "), then remove any white spaces before and 
// after the title.
var pageTitle = document.getElementsByTagName("title")[0].innerHTML
   .replace("Pages - ", "").replace(/^\s\s*/, "").replace(/\s\s*$/, "");

// If the current site is the same as the site collection (meaning it is
// not a subsite), then use the url of the current page.
if (subsite == siteCollection) {
 // Create the string that will contain the breadcrumb trail.
 var text = "<a href='" + siteCollectionUrl + "'>" + siteCollection 
 + "</a> > <a href='" + document.URL + "'>" + pageTitle + "</a>";
// In any other case, use the url of the subsite. 
else {
 // Create the string that will contain the breadcrumb trail.
 var text = "<a href='" + siteCollectionUrl + "'>" + siteCollection 
 + "</a> > <a href='" + subsiteUrl + "'>" + subsite + "</a>";

$(function runMe() {
 // Set the ID of your subsite navigation. 
 var $this = $("#NavRootAspMenu");
 if($this != null) {
  // Remove the class "static" from the last item in the navigation 
  // (because it(s a link to edit the navigation) and remove the last
  // child element (since this doesn't have a href attribute).
   var elem = $($this).find("li.static")[i]; 
   // If elem finds an anchor tag that contains the following class, then
   // add a new class. We'll use this class for the parent elements.
   if ($(elem).find("a").hasClass("ms-core-listMenu-selected")) {
  // If the subsite navigation contains elements with the class 
  // "parentSelected" and that element contains an anchor, a span and
  // another span with the class "menu-item-text", then for each of those
  // elements do the following. 
  $this.find(".parentSelected > a span")
   .each(function(j) { 
   $(this).addClass("bcn");  //bcn = breadcrumbnode
   var crumbLink = $($this).find(".parentSelected > a")[j].href;
   var crumbName = $("")[j].innerHTML;
   // If the link equals the url of the site collection, then this list
   // item is a category and it does not require an anchor tag.
   if (crumbLink == "") {
    text = text + " > " + crumbName;
   // In any other case, this list item has a page and we will add an
   // anchor tag to the breadcrumb trail. 
   else {
   text = text + " > <a href='" + crumbLink + "'>" + crumbName + "</a>";
// When we ran through the navigation, apply the new breadcrumb trail to
// the element in the master page. 
document.getElementById("customBreadcrumb").innerHTML = text;

You'll also need to have the jQuery library for SharePoint Web Services, you can find it here.
In order for our code to work properly, we will need to replace some code from the master page and add a reference to the breadcrumb script on the master page. Be sure to read the JavaScript code first, you will need to fill in a name for your site collection (var siteCollection) and give the url of your site collection followed by a slash (var crumbLink).

Adding a reference to the master page

If we want to apply this code on the site collection and all subsites, then we should add a reference to our script in the master page. Please do note that I'm using a HTML master page. This is the code you should add:
<!--SPM:<SharePoint:ScriptLink language="javascript" ID="scriptLink1"
runat="server" name="~sitecollection/Style Library/Scripts/breadcrumb.js"
OnDemand="false" Localizable="false"/>-->

Do note that the ID might be different. You must make sure that you do not already have a scriptlink with the same ID, so change the number of the ID and make it unique.
Also, the name (path to your script) might be different. Make sure that it matches the path of where your script is located.

Replacing code in the master page

Next, we need to replace some code in the master page. In my HTML master page, I replaced any piece of code that had to do with the breadcrumb. Just to give you an idea, the following pieces of code are the ones that I REMOVED from my master page:
<!--SPM:<asp:sitemappath runat="server" 
<!--SPM:<SharePoint:AjaxDelta id="DeltaPlaceHolderPageTitleInTitleArea" 
<!--SPM:<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"></span>
 <span class="ms-accessible" id="ms-pageDescription">
  <!--SPM:<asp:ContentPlaceHolder id="PlaceHolderPageDescription" 
 <!--SPM:<SharePoint:ScriptBlock runat="server">-->

It is very important that you keep the following code in your master page, but wrap something around it with a class. Like so:
<span class="hideDefaultBreadcrumb">
 <!--SPM:<asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" 
  <!--SPM:<SharePoint:SPTitleBreadcrumb runat="server"

Then add the class to your style sheet:
.hideDefaultBreadcrumb {
 display: none;

The reason that we must keep this content placeholder, is that otherwise you'll suddenly miss a great portion of the "Apps you can add". I forgot about this at first and then suddenly had only three apps left, but after reading about it here I learned that I should have left in the content placeholder with ID PlaceHolderPageTitleInTitleArea. So that's fixed now.

I also removed a span with the ID "ctl00_DeltaPlaceHolderPageTitleInTitleArea" in the master page.

Bear in mind that your code might be different from mine, so always check your site with source view in your browser, to see the ID's and classes of the elements in the breadcrumb.
Now, ADD the following code to the location of where you just removed the piece of code that was previously your breadcrumb:
<span id="customBreadcrumb"></span>

In that tiny span, your breadcrumb trail will appear. This will be dynamically filled with text and links once your script is running.

Make sure your master page and your script are checked in. Now you can finally see the full breadcrumb trail, with the correct hierarchy!
No need to deploy solutions, no need to find a workaround or use webparts to do the trick, just some simple JavaScript is all you need. ;)



  1. Wonderful article, I have some questions on how to install this for my site...

    1. Where do I add the first part of the script to, is it on the subsite layout file

    1. There is no need to store scripts on the subsite, just access the Style Library folder on your top level site using SharePoint Designer, and create a folder there named "Scripts". In this folder you can store all your JavaScript files. To use this code on all subsites, just add a reference in your master page to this script. See "Adding a reference to the master page" in the article for more info.

  2. Hi spservice method is not ever trigering. Is there something that i have to include? Can you please provide the step by step procedure to make this work?

    1. As I mentioned in my article, you will need the SPServices library. You can download it here:
      In my environment, I added the scripts for SPServices to my "Scripts" folder under my "Style Library" folder. Then I added a reference to the SPServices script in my master page.

  3. Impressive. I did not know you could do this all client side with jQuery. Well done.

  4. if i at document library or list. breadcrumb not working.. :(

    1. That's true, it won't work when you're on a document library or a list. I didn't program it that way, but I suppose with a bit of tweaking you can get it to work the way you want it to.