In this blog post I will walk through how to add a custom button to the new SharePoint 2010 ribbon. One very big and noticeable update in SharePoint 2010 is that we now have an awesome, Office client-like ribbon the provides most of the controls and buttons now in SharePoint 2010. A question that has come up on my current project is, how can we add new buttons to it that do cool stuff, like popup dialogs and so forth? In this post I will walk through just adding a custom button, but in an upcoming post I will walk through how to make a popup dialog render when a custom button is clicked.
For reference, the version of SharePoint 2010 I am using is 14.0.4605.1000. This version is newer than Beta 1 (also called Technical Preview) but not quite full Beta 2. So I unfortunately can’t guaranty that these steps will work in full Beta 2 or RTM. But nevertheless, I hope the process I use and my notes along the way can be useful!
Step 1: Create Feature Definition File
The first step to adding a custom button is to create a new feature definition file. This schema has changed very little since SharePoint 2007. In fact, I have been using old SharePoint 2007 samples as my base and not changing anything and they work great!
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
Id="afe52f83-a20e-42d4-8aa7-35d8c5fdfb39"
Title="Skynet Custom Ribbon Button"
Scope="Web"
Description="Skynet Custom Ribbon Button"
ImageUrl="Skynet/WinEarth32x32.png">
<ElementManifests>
<ElementManifest Location="RibbonButton.xml"/>
</ElementManifests>
</Feature>
Step 2: Create Feature Elements File
Just like back in SharePoint 2007, we still need to create feature “Elements.xml” files. In this case I am calling mine “RibbonButton.xml”. This file contains the real information that dictates what kind of button is shown, what happens when you click on it and so forth.
There are a number of important things to point out about the XML snippet below. First is that in contrast to current documentation, I still needed to add lines 6 and 7 below where I am specifying that this CustomAction is geared for a Document Library list type – hence “101”, the code for Document Library which hasn’t changed since the last version of SharePoint and even the one before that if I am not mistaken.
Another item to note is line 8, the “Location” attribute. In Beta 1 we had to use “ViewToolbar” this has now been changed to “CommandUI.Ribbon”.
The attribute “Sequence” below on line 9, just as in the past, specifies the ordering of the button, now in terms of left to right as we are in the context of the horizontally aligned ribbon. The value “5” in this case is pretty low, so in my example this makes my custom button the first in its grouping (shown in screen shot below).
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
Id="SkynetCustomRibbonButton"
RegistrationId="101"
RegistrationType="List"
Location="CommandUI.Ribbon"
Sequence="5"
Title="Move Documents">
<CommandUIExtension>
<CommandUIDefinitions>
<CommandUIDefinition Location="Ribbon.Documents.Manage.Controls._children">
<Button
Id="Ribbon.Documents.New.SkynetTestButton"
Alt="Move Documents"
Sequence="5"
Command="Skynet_Test_Button"
Image32by32="/_layouts/images/Skynet/WinEarth32x32.png"
Image16by16="/_layouts/images/Skynet/WinEarth16x16.png"
LabelText="Move Documents"
TemplateAlias="o1" />
</CommandUIDefinition>
</CommandUIDefinitions>
<CommandUIHandlers>
<CommandUIHandler
Command="Skynet_Test_Button"
CommandAction="javascript:alert('SharePoint 2010 Rocks!');" />
</CommandUIHandlers>
</CommandUIExtension>
</CustomAction>
</Elements>
Looking down the XML snippet, we get to line 14. Here we specify the “Location” of the button in the ribbon.
The schema here is basically: Ribbon.[Tab].[Group].Controls._children
Because the exact schema for these locations is not yet published, one learning tool I’ve been using is checking out the built-in features that come out of the box with SharePoint 2010 in the 14 Hive in the TEMPLATE\FEATURES folder. There are a number of features in there like In Place Records Management or Document Sets where you can get ideas of where that feature’s custom buttons are placed and then snag that location.
Another attribute to talk on is “Command” on line 19. Here we specify the name of the command which links together the “CommandUIDefinition” with its related “CommandUIHandler”. The “CommandUIDefinition” defines where the button goes and how it looks while the “CommandUIHandler” specifies the action that takes place when the button is clicked.
On line 23 is “TemplateAlias”. This was one I was not quite sure about until I messed around with it a bit and found that when I made the value “o2” it made the button into the smaller, 16 x 16 version of itself.
There is a lot more that you can do with this schema, such as specifying how the ribbon should scale on itself when the browser window is resized, such as which buttons take priority over others when ribbon space is reduced. Also, there are other types of ribbon controls and buttons you can use. One type you can get an idea from looking at the In Place Records Management feature schema is grouping multiple buttons under one parent drop down button.
Moving on to the “CommandUIHandler” section, there are some interesting items here to note as well. On line 29 we have our “Command” attribute again that links this “CommandUIHandler” with our “CommandUIDefinition” above.
More importantly is the “CommandAction” attribute. In Beta 1 this was called “CommandScript”, this has now been changed to “CommandAction” in this later build and I understand this will stay. In this attribute we specify the JavaScript that is invoked when the button is clicked. There are really an unlimited number of options of things you could do here. Some options include navigating to a different page, popping up an AJAX dialog, or performing actions on selected items. This is all possible now by using the new JavaScript SharePoint API. In my next blog post, I will walk through showing how to pop up an AJAX dialog box using the new JavaScript SharePoint API.
And that’s it for coding! The next step is just deploying the feature.
Step 3: Deploy Feature to SharePoint
There are now a number of ways to deploy features to SharePoint 2010. STSADM is still available, however its been deprecated in preference to PowerShell and the vast amount of commandlets that come with it now for SharePoint 2010. Also, if you are using Visual Studio 2010, there have been significant improvements to its SharePoint development extensions that make it a first-class development tool now for SharePoint 2010.
In my case, I’ve been kicking it old school and using STSADM just to see if it still works, which it does! Below is my sample deployment .bat file script:
stsadm -o deactivatefeature -name SkynetCustomRibbonButton -url http://spdev -force
stsadm -o uninstallfeature -name SkynetCustomRibbonButton -force
stsadm -o installfeature -name SkynetCustomRibbonButton -force
stsadm -o activatefeature -name SkynetCustomRibbonButton -url http://spdev -force
pause