Creating a Custom Ribbon Tab in SharePoint 2010


Introduction

 

As a SharePoint developer, mirroring the style of the SharePoint user interface in a custom application is important to create a homogeneous experience for your end users. One of the best opportunities to accomplish this is by creating a custom ribbon tab containing contextualized buttons to suite your application.

In this article I’ll show you have to define a new SharePoint Ribbon Tab which includes a button group and a collection of ribbon buttons like Laugh and Giggle. I’ll discuss how to extend the CUI.Page.PageComponent JavaScript object to quickly configure ribbon button command actions. Finally I’ll discuss how to make your custom ribbon tab available from a Layouts page.

 

 

Deploy a Custom Ribbon Tab Definition

We begin by deploying a custom ribbon tab definition to your SharePoint environment. This is done using the <CustomAction /> element of a SharePoint feature. We begin by defining a <CustomAction /> element with the location of ‘CommandUI.Ribbon.Tabs._children’. This will add our custom ribbon tab defined in the <CommandUIDefinition /> element to the collection of available SharePoint ribbon tabs.

 

Coordinate the Ribbon Tab Using a CUI.Page.PageComponent

 

A SharePoint ribbon tab is comprised of HTML and JavaScript elements. Buttons residing on the ribbon tab are coordinated using JavaScript methods. By following the template used on many of the SharePoint pages we can easily setup the necessary JavaScript methods to orchestrate our ribbon events.

The first step is to create a JavaScript object containing the appropriate JavaScript methods to coordinate the ribbon tab buttons. We start by creating a file named RibbonApp.UI.js and provide an object definition for our custom ribbon page component named ‘RibbonApp.UI.RibbonAppPageComponent’. This JavaScript object derives from ‘CUI.Page.PageComponent’ and provides the necessary methods to coordinate the ribbon tab buttons.

The most important methods of the RibbonAppPageComponent can be found in the prototype definition. Inspecting the methods below you will notice calls to global JavaScript functions getGlobalCommands, commandEnabled and handleCommand.

This sample RibbonAppPageComponent provides a basic framework to support your ribbon tab’s custom commands. The RibbonAppPageComponent can be reused by all of your custom ribbon tabs and it is not necessary to create a custom PageComponent for each tab. Although creating a custom PageComponent to alter or customize the behavior of a specific ribbon tab may be a good option is select circumstances.

 

Adding the Ribbon Tab to a Page

 

Once the ribbon tab is defined and the page component created it is time to add the ribbon to your SharePoint .ASPX page. We start by creating a private method named InitializeRibbon which gets called from the Page_Load method of our SharePoint page. We begin the method by getting a reference to the current SPRibbon element and check to ensure the current ribbon is not NULL.

Once we have a reference to the current ribbon we can begin defining the ribbon behavior. We start by setting some basic ribbon properties and adding the available tabs. The Id passed to the MakeTabAvailable method must match the value defined in our ribbon tab definition. We can also setup the initial ribbon tab. A common tab added to most pages is the ‘Ribbon.Read’ element which provides the page title and description.

The ribbon uses the ‘SP.js’ and ‘SP.Runtime.js’ JavaScripts. To ensure these scripts are registered on our page we make two calls to the RegisterScriptAfterUI method. We would also like to register our RibbonAppPageComponent. The SPRibbonScriptManager contains a method to register this script and call the initialize method after the page is loaded. Unfortunately access to this method is private. To correct this deficiency we created our own RibbonScriptManager class to register and initialize the RibbonAppPageComponent.

 

Finally we need to wire up our ribbon buttons to perform meaningful operations. This is accomplished by creating a list of IRibbonCommands. The simplest ribbon command can be created with the ribbon command name, JavaScript action command and JavaScript enabled command. In the code below we are going to register the Laugh button which has a hardcoded enabled value of ‘true’. When the button is clicked we send an alert to the user.

The enable JavaScript string could easily be turned into a JavaScript method which might inspect the page state to determine button availability. This can be seen in the JSEnableDisable button which defines the enabled script to IsJSEnabled(). The IsJSEnabled() method corresponds to a JavaScript method placed on the page to determine the button state. If a Boolean value of true is returned from the method the JSEnableDisable button will be clickable. If a Boolean value of false is returned the JSEnableDisable button will be disabled.

The final important take away from the script below is the RegisterGetCommandsFunction, RegisterEnabledFunction and RegisterHandleCommandFunction. These are set to the JavaScript method names defined in our RibbonAppPageComponent. The contents of these methods are derived from the list of commands passed to these methods.

Your ribbon tab is now ready. Build and deploy your application to your SharePoint environment and enjoy the fruits of your labor. If you make a lot of changes to your ribbon you will notice IE caches a lot of ribbon content. It may be necessary to delete your cached files after an update or turn off caching all together.

 

Additional Ribbon Commands

 

The SPRibbonCommand is used to interact with page components via JavaScript. Other SPRibbonCommands can be used to provide alternate types of interactions. Other ribbon command types available are the SPRibbonPostBackCommand, , SPRibbonQueryCommand and the SPRibbonPopulateQueryCommand. .NET programmers are accustomed to creating buttons which post back to a code behind page where additional programming actions can be taken. To do this we leverage the SPRibbonPostBackCommand.

To handle the post back event our page must implement the IPostBackEventHandler. The implementation of the RaisePostBackEvent begins by deserializing the SharePoint ribbon post back event and handling the post back ID provided by our post back command.

Conclusion

 

The ribbon is new to SharePoint 2010 and is being embraced by Microsoft. The ribbon is making its way into many Microsoft applications like the Office Suite, WordPad, Paint and Windows 7. Consumers of Microsoft products, including SharePoint users, will come to expect a ribbon driven menu to be included in custom applications.

Creating a custom ribbon tab for your SharePoint application doesn’t have to be a pain and can be accomplished by defining a ribbon tab definition, creating a PageComponet to coordinate ribbon events and initializing the ribbon in your application page. Using a custom ribbon tab is an excellent way to present custom actions in your application while maintaining a cohesive visual experience for your users. Wow your users by including a custom ribbon tab in your next SharePoint application.

Visual Studio solution for ribbon sample

Related Posts

080912_0319_HowtoAddthe1.png 080912_0319_HowtoAddthe2.png 080912_0319_HowtoAddthe3.png 080912_0319_HowtoAddthe4.png 080912_0319_HowtoAddthe5.png 080912_0319_HowtoAddthe6.png 080912_0319_HowtoAddthe7.png 080912_0319_HowtoAddthe8.png 080912_0319_HowtoAddthe9.png 080912_0319_HowtoAddthe10.png 080912_0319_HowtoAddthe11.png 080912_0319_HowtoAddthe12.png

How to Add the Meeting Workspace Button in the Outlook 2010 Ribbon to Create a Meeting Workspace

image.png image_thumb.png SharePointDropDownFilter.png

SharePoint 2010 Tutorial Video: Drop-Down Filters

Loading SharePoint Dlls into Reflector

cmdSysprep.png cmdSysprep_thumb.png startCMDAdmin.png startCMDAdmin_thumb.png cmdBCDEditEnum.png cmdBCDEditEnum_thumb.png cmdBCDEditCopy.png cmdBCDEditCopy_thumb.png cmdMark.png cmdMark_thumb.png cmdHighlight.png cmdHighlight_thumb.png cmdPaste.png cmdPaste_thumb.png cmdBCDEditDevice.png cmdBCDEditDevice_thumb.png cmdBCDEditDetectHAL.png cmdBCDEditDetectHAL_thumb.png

SharePoint 2010 Lab Environment Part 2 – Bootable vhd Files

6 Comments

  1. Avatar of Mehulkuamr Shah

    Mehulkuamr Shah - November 4, 2009, 7:44 am

    HI….. Can u guide me in a detail how i can load the custom ribbon TAB in a page using JAVA script (CUI.Page.PageComponent)…. here in this blog you have not given in detail and i am facing the problem….

  2. Avatar of Andrew

    Andrew - November 11, 2009, 10:09 am

    Hi! Would you please provide the source code of your example to make some details more clear?
    Thanks in advance.

  3. Avatar of Kevin Pine

    Kevin Pine - November 11, 2009, 11:01 am

    Andrew,
    We’ll have a link to the sample Visual Studio solution which contains all the details of how the ribbon is built posted today.

  4. Avatar of Andrew

    Andrew - November 13, 2009, 6:06 am

    Thanks for really helpful article!
    Two remarks:
    1. the VS solution can’t be opened in VS 2010 beta 2 for some reason;
    2. CustomAction xml should be fixed to pass solution validation:
    – for CustomAction node: change Location attribute from ”CommandUI.Ribbon.Tabs._children” to ”CommandUI.Ribbon”
    – for CommandUIDefinition node: add attribute Location=”CommandUI.Ribbon.Tabs._children”

  5. Avatar of Jeremy Luerkens

    Jeremy Luerkens - November 13, 2009, 11:13 am

    This solution was built using Visual Studio 2010 beta 1. When SharePoint 2010 beta 2 is released we’ll try and update the project to operate with the latest release of Visual Studio and SharePoint.

  6. SharePoint 2010 Branding | Sharepoint Sriram - December 10, 2011, 12:31 am

    [...] Creating a Custom Ribbon Tab in SharePoint 2010- SharePoint Solutions.com [...]

Leave a Reply