14 Jan 2015

Display a breadcrumb menu with SharePoint Connector

by GLiNTECH

Some companies may be in the process of migrating from SharePoint to Confluence, or have a need to run both applications side by side. In both situations they will often turn to the SharePoint Connector plugin so they can embed Confluence content within SharePoint pages. With the plugin correctly configured, users are able to view Confluence page content, page attachments and add comments.

There are, however, some drawbacks with this plugin. One of the larger issues is that there's no facility to display the Confluence page hierarchy, making it difficult to navigate between pages.This is particularly a problem in larger Confluence spaces where there may be hundreds of pages.

The Solution

One solution is to add the or macro to the home page of the Confluence space. However, this only works for small spaces where the page hierarchy is quite shallow (2-3 levels of nested pages). For more complicated Confluence spaces, users very quickly lose track of what page they are on, and the Children/Table of Content macros quickly become a horrible mess of hyperlinks cluttering up the page.

A Better Solution

Wouldn't it be nice if we were could display a breadcrumb navigation menu in the SharePoint page? Users would immediately be able to tell where in the page hierarchy they are, and could easily jump back to a particular parent section, or directly to the home page.

The good news is Confluence user macros support the Velocity templating engine. This means we can access the Confluence API to retrieve information about the current page, such as its parent page, id, title and so on. This enables us to build up a list of all the parent pages and render a nicely formatted breadcrumb menu, similar to the one used by Confluence.

Creating the Macro

Navigate to the "User Macros" section on the Confluence Administration page
Create "Create User Macro"
Add the following information

Macro Name: Breadcrumb
Visibility: Visible to all users in the Macro Browser
Macro Title: Breadcrumb Navigation Menu
Description: Displays a breadcrumb trail
Categories: Navigation
Icon URL: (leave blank)
Documentation URL: (leave blank)
Macro Body Processing: Unrendered

Then copy the contents of the below code block into the Template field:

## @noparams
## Macro title: Breadcrumb
## Macro has a body: Y
## Body processing: Rendered
## Output: Selected output option
##
## Developed by: GLiNTECH
## Date created: 12/01/2015
## This macro displays a breadcrumb trail.
  
#set ($pageList = [])
  
## Generates the list of parent pages that will be used to
## create the breadcrumb trail.
#macro(addBreadCrumb $p)
    #if ($p)
        #set ($added = $pageList.add($p))
        #set ($myParent = $p.getParent())
 
        #if ($p.getParent())          
            #addBreadCrumb($p.getParent())
        #else
            #renderBreadCrumb()
        #end
    #end
#end
 
## Renders the breadcrumb hyperlinks
#macro(renderBreadCrumb)
    <div class="gtBreadcrumb">
  
    #foreach($i in [$pageList.size()..1])
        #set ($realIndex = $generalUtil.convertToInteger($i) - 1)
        #set ($p = $pageList.get($realIndex))
 
        #if ($realIndex > 0)
            <a href="/pages/viewpage.action?pageId=$p.getId()">$p.getTitle()</a>&nbsp;/&nbsp;
        #else
            <a href="/pages/viewpage.action?pageId=$pageList.get(0).getId()">$pageList.get(0).getTitle()</a>
        #end
    #end
    </div>
#end
 
#addBreadCrumb($content)
  
<style type="text/css">
.gtBreadcrumb a {
    font-size: large;
}
</style>

How to Use the Macro

Edit a Confluence page
Open the Macro Browser and select the Navigation category
Select the Breadcrumb macro
Save the page

When you navigate to the page, you will see a breadcrumb trail, which will also appear in the embedded page within SharePoint, as shown below: