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.