Customizing the SharePoint 2010 Ribbon

By Altaf Gilani and Mark Massad

With SharePoint 2010, Microsoft continues to leverage its Ribbon UI, introduced with Office 2007. The Ribbon is a context-sensitive interface that groups related tasks into a single tab, and it’s one of the key UI changes for SharePoint 2010. The Ribbon is extensible and offers customization opportunities that can help you enhance SharePoint’s usability.

We’d like to introduce you to making Ribbon customizations and offer some lessons learned from a recent project. We’ll cover some fundamentals, then work through some scenarios and examples.

As you read this article, note that Ribbon customizations fall into two basic groups: customizations needed to add a tab and customizations to existing tabs. The first group takes a bit more effort as you need to work with the Page Manager, while customizations in the second group can be accommodated, for the most part, in the Elements.XML, depending on the action.

SharePoint Ribbon Development

As a developer, you can extend the ribbon declaratively using Server ribbon XML and simple script, or you can use ribbon XML and a page component depending on what you need to do and the techniques you want to standardize your development on.

The packaging is no different than that for any other SharePoint 2010 solution. Helpful resources include the SharePoint SDK and Microsoft’s MSDN site for SharePoint development.

To customize the SharePoint 2010 Ribbon, you begin by editing the CustomAction nodes of the Elements.xml file in any SharePoint 2010 Feature. (To learn more about Features, see the Microsoft webpage “Using Features.”)

Basically, you make references to or add new references for what is called CommandUIDefinitions. This is how customizations are mounted within a Feature. Let’s start by examining the basic structure of this node, which you can see in Figure 1.

First, the CustomAction tag must have an ID that’s unique enough so SharePoint can identity it within a whole collection of Custom Actions that are part of your deployment. The value for Location attribute should always be set to CommandUI.Ribbon to tell SharePoint you’re doing Ribbon customizations with this action.

Second, the CommandUIExtension tag contains CommandUIDefinitions child tags to declare all controls or containers which should be created.

The Ribbon supports several controls to help create the user experience for your project. As you will see in our examples, we work with command buttons but you can also use such things as drop-down menus, check boxes, or spinners, as the interfaces and techniques are the same.

Finally, the CommandUIHandlers tag contains the instructions for executing command actions (e.g., Window pop-up, PostBack event on selected list item).

That’s the basics around customization. We’ll drill down into each area and conclude by providing some customization guidance.

Just keep in mind there are other child tags and attributes to support various customizations, but the ones we present are effectively the minimum.

Types of Ribbon Customization

Because there are many ways to customize the Ribbon, this is where you as the developer get to be creative. Let’s look at the following customization scenarios:

• Adding a tab to the Ribbon
• Adding a group as a container of new controls within an existing tab
• Removing a button from the Ribbon
• Replacing a button on the Ribbon

Adding a Tab to the Ribbon

A scenario that developers are quick to use is the addition of a new tab to the Ribbon. Adding a new tab gives you control over the whole experience, as you are starting with a blank slate.

Let’s create a new tab titled “ix Ribbon Page” and add it to the Ribbon so that it’s visible when the user is on a site. The new tab, which Figure 2 shows, includes two groups, “New” and “Test Functions,” and four buttons:

• New Popup: Opens a test page using the SPModal Dialog framework.
• Hello Alert: Pops up a simple JavaScript alert.
• GoodBye PostBack: Uses JavaScript to PostBack to the page for some operation.
• SeeYa Navigate: Uses JavaScript to navigate to another page.

To start creating the new tab, copy the ribbon XML in Figure 3  into the Elements.xml file.


This includes everything needed to design the action so it can be included in a Feature, implemented in the UI, and define what each control does for the user.

After we get beyond the UI of the Tab/Group/Button behavior, we’ll look at the CommandUIHandlers element. We think you’ll find this element equally or perhaps more interesting.

Adding a Group as a Container of Controls within an Existing Tab

Sometimes you’ll need to add a new group and a collection of controls to a tab. To add a group, identify the tab on the Ribbon where the group will appear, then define the controls inside the group to specify how the group renders these controls.

The example in Figure 4 adds a new group, “My Custom Group,” with two buttons, to the out-of-the-box Page tab on a site.

An important thing to note when using groups is to be sure you have a corresponding MaxSize attribute for each group. Without this element, you’ll get XML validation errors when SharePoint tries to render the customization.

For example, you could see the error message “ArgumentException: Ribbon ‘Tab’ node must have a ‘Scaling’ subnode.” The problem might not necessarily just be a Scaling subnode issue. It could be incorrect size attributes or missing associations.

Check your XML structure, as a lot of issues seem to trigger this message.

Removing a Button from the Ribbon

Sometimes a business will want to remove SharePoint functionality for some reason. Removing a button from the Ribbon is one example of a technique you might use to “dim down” the SharePoint experience.

To remove a button, you simply need to define the location of the button you want to remove and wrap this into a HideCustomAction element within the Elements.XML of the Feature. Figure 5 shows XML that removes the Connect to Outlook button from the Library tab in the Actions group for a document library.

The HideCustomAction element is useful for trimming out other functions in SharePoint beyond the Ribbon. For more use cases and specifics, see the Microsoft webpage “Default Custom Action Locations and IDs." This element is a very useful and powerful feature for controlling the entire SharePoint experience and trimming out unnecessary functionality.

Replacing a Button on the Ribbon

Sometimes a business might need to replace existing buttons on the Ribbon rather than replacing or creating a new tab. For example, you might need to direct the user to a custom data entry form when a new item is selected or replace an out-of-the-box button with something else.

 

 

The easiest way to implement this is to create a CustomAction element in the Elements.xml file, making a reference to the existing Ribbon and button IDs and replacing that entry with your own.

You will also need to implement a CommandUIHandler that corresponds with the command associated with your button (we’ll get into some options later).

In the example in Figure 6, we replace the Connect to Client Actions button with a simple Replaced button and JavaScript function that pops open an alert. Let’s drill down into key aspects of the implementation.

Custom Action. The Custom Action element in the Elements.xml file is used to create an extension to the UI or, in this case, to customize the SharePoint Ribbon.

Be sure to look at the specification in the Attributes table at Microsoft’s “CustomAction Element” webpage as you will see several attributes that let you control the user experience in many different ways, including more than just in the Ribbon.

The attributes “Rights” and “RequireSiteAdministration” are particularly useful for customizing the UI based on role or permissions set. These provide another dimension of flexibility to support your use cases by providing role and permission information for use in your logic.

For example, you might want to disable, remove, or add certain controls based on rights. We see this requirement occasionally to simplify the user experience or provide targeted features based on permissions and role. The key is to map out these use cases and design your CustomActions accordingly.

CommandUIDefinition. The CommandUIDefinition element defines how the controls will be displayed within your extension. It provides definitions for tabs, groups and controls.

In many of the samples in the SDK, you will notice a “_children” convention such as “<CommandUIDefinition Location=”Ribbon.Tabs._children.” It’s like a convention for making functions available to all aspects of the user context (e.g., List, View, Items Edit).

You can find examples online or in the SDK to help you with your control selection and arrangement. We found that the CMDUI.XML file in the SharePoint 14 Directory was a very helpful resource in terms of understanding arrangements used to make up the out-of-the-box UI.

Fortunately, the SharePoint team made this available as XML to fasttrack our efforts. See Microsoft’s webpage “Default Server Ribbon Customization Locations” to learn more.

CommandUIHandler. This is where the rubber meets the road: The CommandUIHandler attribute lets you specify script for command execution methods such as alerts, PostBacks, and redirects.

You can also include substitution tokens that are transformed at rendering (e.g., \\{ItemId\\}, \\{SiteUrl\\}). To understand more of these options available to you as a developer, see the Microsoft webpage “CommandUIHandler” and its attributes table.

Now, going back to our first example, two of our favorite techniques are shown in the following figures. Figure 7 shows how to use a PostBack command handler. Figure 8 shows how to use the SharePoint UI Modal Dialog framework.

As simple as they are, these two methods are very powerful and can help you expand the whole SharePoint user experience very quickly and with precision. You can include controls in the Ribbon that do more than simple JavaScript popups. You can also hook-in callback methods into the parent page for using the SP.UI.Notify.addNotification in your CommandActions as well.

Lessons Learned

Here are some lessons we learned on a recent project we did that might help in your next Ribbon customization experience. They are as follows:

1. When developing Ribbon customizations, be sure to close and open a new browser during your tests to ensure you are running the latest script (or use In-Private Browsing in IE).
    
2. Refer to the CMDUI.XML file in the SharePoint 14 Directory to see how the out-of-the box tabs are configured.
    
3. Use the built-in SharePoint Pop-Up framework to instantiate Custom Application pages that you might need to invoke using the Ribbon for consistent user experience.
    
4. Don’t be afraid to combine numerous actions into a single Elements.xml file for data consolidation or creating larger features.
    
5. Know that Ribbon customizations can be added to Custom Application pages as well as to Web Parts and that there are benefits going either way.
    
6. Try to remove/replace/add controls to existing out-of-the-box tabs if your design supports this model. You’ll incur less overhead in making changes to the Ribbon than from writing new tabs from scratch.
    
7. Be sure to understand all communication methods available for the Ribbon. For example, you can use a PostBack by implementing the IPostBackEventHandler and deserialize the EVENTARGUMENT in code, but it’s no different than doing this with other controls in .NET.
    
8. We’ve tried using a Ribbon Manager that’s been floating around many of the blogs. It handles interfaces with the page, which seemed to make things easier and our code cleaner for new tabs. However, we suggest you first understand interactions with the Page Manager before including this component and taking on ownership within your project.
    
9. Make good design decisions around the user experience and type of Ribbon customizations. For example, we developed some contextual tabs that weren’t as intuitive to the users as we envisioned. We created new tabs when all we needed to do was change out, delete, and add some buttons.
    
10. We suggest framing out a simple Ribbon solution to fully define variations and coding practices for your project. In other words, handling the presentation of tabs, groups, and commands, various pop-ups, PostBacks, redirect events, and more requires good organization and packaging.

Happy Coding!

It’s exciting to have the ability to customize the Ribbon to the extent that we can. For many projects, this is the right place to centralize many of the actions that make up the user experience. Certainly, there are many other aspects of using the SharePoint Ribbon, but we hope we gave you a good overview of what’s possible by sharing what we’ve learned.