Extending the SharePoint 2010 Ribbon Quick Access Toolbar

Custom button added to the Quick Access Toolbar in SharePoint 2010
SharePoint 2010 includes the Ribbon which makes it easier for users to work with the rich functionality of the SharePoint platform. The Ribbon in SharePoint 2010 also includes a rich extensibility framework which makes it possible for custom solutions to make their functionality available to users. Using the Ribbon extensibility framework you can add all kinds of controls to the Ribbon but is it also possible to extend the Quick Access Toolbar?

Ribbon in SharePoint 2010

Ribbon in SharePoint 2010

SharePoint 2010 includes the Ribbon which makes it easier for users to use SharePoint. Comparing to traditional menus, the Ribbon is more task oriented what makes it easier for users to discover commands that they need. Additionally, since the Ribbon is context-aware, it keeps the UI clutter to the minimum making sure that users will not see options they cannot use at the given moment.

While working on SharePoint 2010 Microsoft did more than simply implement the Ribbon which has been proving its superiority over menus since Office 2007. Microsoft also provided us with a great framework for extending the Ribbon with custom functionality. Fellow SharePoint MVPs Andrew Connell, Chris O’Brien and Wictor Wilén wrote some great articles about utilizing the Ribbon extensibility framework in your custom solutions. There is however one more question regarding Ribbon extensibility: how do you customize the Quick Access Toolbar?

What’s with the Quick Access Toolbar?

Ribbon cannot be customized by users. Additional controls can be added by custom extensions but as a user you cannot change anything about the Ribbon. There are however situations, when you might be frequently running some specific action and two clicks might be just one-too-many. For all those scenarios Microsoft provided us with the Quick Access Toolbar, which is displayed on the title bar of the application’s window.

Quick Access Toolbar in Word 2010

As a user you can customize the Quick Access Toolbar and make it contain the options that you are using the most.

Just as SharePoint 2010 contains the Ribbon it also contains the Quick Access Toolbar. In SharePoint 2010 it’s located just between the Site Actions menu and the Ribbon Tabs.

Quick Access Toolbar in SharePoint 2010

By default the Quick Access Toolbar in SharePoint 2010 contains the Navigation control (also known as the new breadcrumbs) and the Edit/Save Page button. Comparing to the Office clients, SharePoint 2010 doesn’t allow users to customize the Quick Access Toolbar. Additionally, despite the fact that SharePoint 2010 Ribbon is highly extensible, there is no API/markup to add a custom button to the Quick Access Toolbar in SharePoint 2010. So is this requirement really a no-go or is there a way after all?

Extending the Quick Access Toolbar in SharePoint 2010

Important Before we move on and take a look at how you could extend the Quick Access Toolbar in SharePoint 2010 it is important to notice that there is no supported way of doing this in SharePoint 2010. The approach I have used is based on markup manipulation and there is no guarantee that this will keep working in the future. It is also possible that this might break on a different Master Page so it is very important that you test your solution thoroughly before implementing it in production.

A while ago I published the Mavention Instant Page Create solution that allowed you to create a Publishing Page with a single mouse click. That solution was based on a custom button added to the Quick Access Toolbar:

Mavention Instant Page Create button added to the Quick Access Toolbar

So how did I do it exactly?

There are basically two approaches to extend the Quick Access Toolbar. Both of them include JavaScript and DOM manipulation. The real difference is whether they are supported in Sandbox or not and how they deal with handling the click event of the button.

Adding a new button to the Quick Access Toolbar using a Sandboxed Solution

Start off by creating a new project called ExtendingQuickAccessToolbar.Sandbox using the Empty Project project template. Since this approach is compatible with the Sandbox you can choose Sandbox as the solution type.

Next add a new Empty Element called LoadJavaScriptCustomAction to the project. This Empty Element will allow you to make your custom button available globally within the whole Site Collection. Ensure that the newly created Empty Element is open and paste the following contents in it:

<?xml version="1.0" encoding="utf-8"?>  
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">  
  <CustomAction 
    ScriptSrc="~SiteCollection/Style Library/jquery-1.5.2.min.js" 
    Location="ScriptLink" 
    Sequence="100"/>
  <CustomAction
    ScriptSrc="~SiteCollection/Style Library/ExtendQuickAccessToolbar.js"
    Location="ScriptLink"
    Sequence="200"/>
</Elements>  

As you might have noticed I have chosen to use jQuery in this sample. Although it isn’t absolutely necessary, it simplifies manipulating the DOM of the Quick Access Toolbar a lot.

Next add a new Module called JavaScript. Add jQuery  to this Module as well as a new JScript file called ExtendQuickAccessToolbar.js. This will be your custom JavaScript file where you will create a new button and add it to the Quick Access Toolbar.

Open the ExtendQuickAccessToolbar.js file and paste the following contents:

$(function () {
    $('#RibbonContainer-TabRowLeft a:last').after(function () {
        return $('<a href="#" class="ms-qatbutton ms-rtefocus-invalid" title="Hello World"><span style="position: relative; width: 16px; display: inline-block; height: 16px; overflow: hidden"><img style="border: 0px" alt="Hello World" src="/_layouts/images/backarrow.png"></span></a>').click(function () {
            SP.UI.Notify.addNotification('Hello World');
            return false;
        });
    });
});

This code waits until the page loads, selects the last button from the Quick Access Toolbar and adds after it a new hyperlink. The created hyperlink has a click event associated with it, which will display a Notification Message after clicking the button.

Before we test if everything is working correctly let’s verify the contents of the Elements.xml file of the JavaScript module:

<?xml version="1.0" encoding="utf-8"?>  
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">  
  <Module Name="JavaScript" Url="Style Library">
    <File Path="JavaScript\ExtendQuickAccessToolbar.js" Url="ExtendQuickAccessToolbar.js" Type="GhostableInLibrary" />
    <File Path="JavaScript\jquery-1.5.2.min.js" Url="jquery-1.5.2.min.js" Type="GhostableInLibrary" />
  </Module>
</Elements>  

The important parts here are the Url and Type attributes which are different than the default values.

If you deploy the Solution to a SharePoint site you should see a new button on the Quick Access Toolbar:

Custom button added to the Quick Access Toolbar

Once you click a Notification Message will appear on the screen.

‘Hello World’ notification message after clicking the custom button on the Quick Access Toolbar

Although the logic behind the button in this sample is very simple, you could extend it using things such as the SharePoint 2010 JavaScript Object Model or custom Web/WCF services (assuming those are already available to you, since you cannot deploy custom Web/WCF services using Sandboxed Solutions).

Adding a new button to the Quick Access Toolbar using a Delegate Control and a Farm Solution

Another approach to add a custom button to the Quick Access Toolbar is to use a Delegate Control to register the JavaScript and hook up the button’s click event handler. Using a Delegate Control gives you the ability to use code-behind for handling the click event, which allow you to create richer and a more complete solution. The downside is, that because Delegate Controls are not supported in Sandboxed Solutions, there might be situations when this approach is not possible.

Important Before you proceed, don’t forget to retract the previously created Sandboxed Solution to ensure that you won’t get the same button twice.

First add a new SharePoint project called ExtendingQuickAccessToolbar to the solution. Be sure to choose Farm as the solution type.

Next add the Layouts Mapped Folder to your project and add to it jQuery and a custom JScript file called ExtendingQuickAccessToolbar.js. The contents of this file are similar to the one we used in the Sandboxed approach except for the fact that we can now call a postback method that we can handle in the code behind of the Delegate Control:

$(function () {
    $('#RibbonContainer-TabRowLeft a:last').after(function () {
        return $('<a href="#" class="ms-qatbutton ms-rtefocus-invalid" title="Hello World"><span style="position: relative; width: 16px; display: inline-block; height: 16px; overflow: hidden"><img style="border: 0px" alt="Hello World" src="/_layouts/images/backarrow.png"></span></a>').click(function () {
            __doPostBack('CustomQuickAccessToolbarButton', '');
        });
    });
});

The last step is to add the Delegate Control to the project. For this add the ControlTemplates Mapped Folder to your project. Add a new User Control called CustomQuickAccessToolbarButton to the ControlTemplates Mapped Folder.

In the ASCX of the User Control add references to both JavaScript files:

<script type="text/javascript" src="/_layouts/ExtendingQuickAccessToolbar/jquery-1.5.2.min.js"></script>  
<script type="text/javascript" src="/_layouts/ExtendingQuickAccessToolbar/ExtendingQuickAccessToolbar.js"></script>  

In the code behind of the User Control, add the following code snippet in the Page_Load method:

if (IsPostBack && Request["__EVENTTARGET"] == "CustomQuickAccessToolbarButton")  
{
    // handle the click event here
}

On each load the User Control will check if it’s a postback and if it has been called by our button.

If you deploy the solution you should see the same button added to the Quick Access Toolbar. Although we haven’t implemented any server-side behavior so you won’t see much after clicking it, you could attach a breakpoint to confirm that everything has been wired up correctly.

Summary

SharePoint 2010 includes Ribbon which allows users to use the functionality of the SharePoint platform in a user-friendly manner. Although the Ribbon has a rich extensibility framework, there is no supported way of customizing the Quick Access Toolbar. Depending on your scenario there are two approaches that you could consider for adding a custom button to the Quick Access Toolbar. The samples above provide you with a starting point to include in your custom solutions.

Technorati Tags: SharePoint 2010,Ribbon

Comments

comments powered by Disqus