Basics: Add a simple JavaScript button on the SP2010 ribbon

Single Button addition on the SharePoint 2010 Ribbon, using the available tabs and groups (no new definitions)!

This is the first and simplest example of Ribbon customisation. More complex examples will follow. If you need a quick introduction to the SP2010 Ribbon before following through this example, please do jump here, where I explain the Ribbon basics.

In this example, we will mention all the absolutely necessary elements that your elements.xml needs to have in order to add a single button on the ribbon. Its usability will be limited to the display of a simple message box.

First of all, we need to ensure that we know what we are expected to do in order to customise the ribbon. Ribbon customisations are performed by the introduction of new features. New features are created in Visual Studio as new SharePoint projects onto which we simply add a new emply element file.

If you want to follow through the example, open up Visual Studio, click on New Project, select New Empty SharePoint Project -found in the SharePoint 2010 section of the available projects, give it a title, make sure you’re targeting the 3.5 .NET FrameWork (the dropdown menu on the top of the dialog box) and you’re set to go. You should now be looking at a blank project, made up of some items on the right hand side column. Right click on your project name and select Add and then New Item in the followin menu. Towards the bottom of the list you will notice the Empty Element. Click on it, give it a sensible name and add it to your solution.

As soon as you add the Empty Element to your solution, there will appear a .feature item under the Features section in your solution. You want to double click on that and set its properties (ie. the name, since this is the one you will be seeing in the SharePoint Features Management page, and of course, most importantly, the scope of the feature, ie. where, will this new feature be available – web will be the most common option). Also, you may want to rename the Feature itself, otherwise it will appear as Feature1 in your SharePoint installation.

When you’re done with editing the details, you’re ready to create the actual customisation. Note that althought you altered the feature details, the code for your feature will go into the elements file that you added earlier. So, double click on your element file in your solution to open it up in your editor. What you now need to make sure, is that you contain all of the following in your element file:

1. define your xml version and encoding, ie. <?xml version=”1.0″ encoding=”utf-8″?>
2. point to the correct namespace binding (xmlns) by using the appropriate reserved attribute, ie. <Elements xmlns=http://schemas.microsoft.com/sharepoint/>

Once you’ve got those two, you need to start thinking about the xml that will form your customisation. The following order is what will definitely be required for your customisation to appear (missing any of those or mistyping something will render your customisation invisible even if Visual Studio reports that the deployment was successful!).

You need:
i. a CustomAction with at least an Id and Location, which will define on which ribbon your customisation will appear (the diplay, edit or new form ribbons or everywhere on the site, on the main ribbon).
ii. a CommandUIExtension encompassing a CommandUIDefinitions that in turn encompasses one or multiple CommandUIDefinition tags.
iii. your CommandUIDefinition will at least require a Location, which is the location where your customisation will appear on the user interface.
iv. Inside the single or multipe CommandUIDefinition, you will add your customisation. In our example, we’re simply adding a button so, you need to define a new Button with an Id, an Image32x32 (which is the image that will be displayed on the button), a LabelText (which is the text that will be displayed under your button), a Command (which is the action that will be performed once the button has been clicked), a TemplateAlias (which will need be defined in your own XML or be one of the available ones in the default list of templates in cmdui.xml) and possibly a Sequence (which defines the order in which the customisations will appear – it is not essential but if it is not provided, the customisation will always appear last). Notice that the Button is a closed tab, ie. you dont add </button> in order to close it but you rather end the first tag with />.
v. Once you’ve added the button, you close the CommandUIDefinition and if you’re not adding another one (another CommandUIDefinition) you also need to close the CommandUIDefinitions tag.
vi. After you’ve closed your definitions tag, you need to provide the code that will run once your button has been clicked. The actual command that will be executed, is always placed in a CommandUIHandler tag, which needs to be placed in a CommandUIHandlers tag (like the defitions that were placed inside a CommandUIDefinitions tag). So, open a CommandUIHandlers tag and then add a single CommandUIHandler tag.
vii. Your CommandUIHandler will be a closed tag that will provide at least two elements: the Command, which needs be named just like you named the Command attribute of your Button in your CommandUIDefinition, and the CommandAction that will be whatever you need the button to do. In any case, it will be inline JavaScript.
viii. Once you’ve completed the handler, close your CommandUIHandlers (unless you need to add more than one handler, not applicable in this example), close the CommandUIExtension, close the CustomAction tag and finally close the Elements tag. If all has gone according to plan, you can now click on Build and select Deploy solution (on the Visual Studio menu on the top). Your new customisation will appear in the features list of your websites (if you’ve selected this to be a web solution when selecting options for the new feature).

<?xml version=”1.0″ encoding=”utf-8″?><Elements xmlns=”http://schemas.microsoft.com/sharepoint/“>
<CustomAction
Id=”Test_Button”
Location=”CommandUI.Ribbon”>
<CommandUIExtension>
<CommandUIDefinitions>
<CommandUIDefinition
Location=”Ribbon.Documents.New.Controls._children”>
<Button Id=”Ribbon.Documents.New.RibbonTest”
Alt=”Test Button”
Sequence=”8″
Command=”Test_Button”
LabelText=”Click me!”
Image32by32=”C:\Users\User\Desktop\icon.jpg”
TemplateAlias=”o1″ />
</CommandUIDefinition>
</CommandUIDefinitions>
<CommandUIHandlers>
<CommandUIHandler
Command=”Test_Button”
CommandAction=”javascript:alert(‘I am a test!’);” />
</CommandUIHandlers>
</CommandUIExtension>
</CustomAction>
</Elements>

1. Edit: Although I did mention what the TemplateAlias is, I forgot to say what o1 is and whether there are other o’s. There are two actually: o1 and o2. o1 will make your custom button appear as a 32×32 icon whereas, 02 will display a 16×16 icon on your ribbon. As I already said, you can define your very own XML but you can always use the default ones for speed and consistency.

Obviously, you will need an icon for your new button and the best practice would be to NOT include your icon on your desktop like I did in my example. I just have this one icon that I reference from all my solutions and I’m just too lazy to copy it in the correct folders for each solution. What you’re aiming at, is to add your icon in a subfolder of your solution and then reference it relatively instead of absolutely as in my example.
From this little example, it becomes obvious that the following structure is absolutely essential when customising the ribbon. For more complex customisation, the structure will obviously be more complex but this is the absolute minimum:

<Elements>
<CustomAction>
<CommandUIExtention>
<CommandUIDefinitions>
<CommandUIDefinition></CommandUIDefinition>
</CommandUIDefinitions>
<CommandUIHandlers>
<CommandUIHandler></CommandUIHandler>
</CommandUIHandlers>
</CommandUIExtension>
</CustomAction>
</Elements>

An example of adding new tab and controls on this new custom tab will follow shortly.