Home > 2010, Development, Ribbon > HOWTO: Add a button to the ribbon in SharePoint 2010

HOWTO: Add a button to the ribbon in SharePoint 2010


This post is intended for BETA1. It will work on BETA2 as well, just remove the … for

After a few hours of messing around in XML, we (Jopx and I) figured out how to put a button on the Ribbon. First of all, how does it work? There is some XML (located in the 14 hive/templates/global/xml) in a file called CMDGui.XML. This contains the entire Ribbon XML that is used to render the ribbon. To get that XML into a Ribbon, there are two javascript files that translate that data into a workeable ribbon (CUI.js and SP.Ribbon.js). What do we need to do to create our custom button? It’s quite simple, you just create some XML, push it to the SharePoint environment by making use of an empty element, add some stuff to the templates/xml folder and you’re set. That is once you figured it all out 🙂

First of all, create a new Empty SharePoint project in Visual Studio. (no screenshots after this as my laptop here can’t run SP2010)

image

  • Rename your project to MyCoolButton
  • Add an empty Element.
  • In that element, paste the following xml:
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="MeSoCool" Location="CommandUI.Ribbon.Documents.New.Controls._children">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="CommandUI.Ribbon.Documents.New.Controls._children">
          <Button Id="Ribbon.Documents.New.Controls.MyCoolButton"
                  Image16by16="/_layouts/images/edit.gif"
                  Image32by32="/_layouts/images/placeholder32x32.png"
                  Description="MyDescription"
                  Command="MyCoolButton"
                  LabelText="Banzai"
                  Sequence="60"
                  TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
    </CommandUIExtension>
  </CustomAction>
</Elements>

What does all this XML mean?

First of all we will be adding a CustomAction, and the most important attribute there is the Location. This location attribute will define where the button is going to appear. Notice that the same attribute is also defined in the CustomUIDefinition which is the location where it will need to be defined in Beta2. So in Beta1 apply the Location to the CustomAction, in Beta2 only apply the location to the CommandUIDefinition. Notice the _children in the end, you need to add it to be able to add buttons to that Control collection.

Where does this location come from? In the CMDGui.XML file that location is defined in a group. This group is part of a group collection called Ribbon.Documents.Groups which is part of the Tab called Ribbon.Documents.  This tab is the ribbon we will see when we are working with documents. Important to notice is the Template the group is using. If the Template used is Ribbon.Templates.Flexible2 you can add buttons to that group. If it isn’t a flexible template (like Ribbon.Templates.ThreeRowsSixAlignedControls2) then you can’t add buttons as those are fixed templates. As an example I added the xml for the Ribbon.Documents.New group.

<Group
            Id="Ribbon.Documents.New"
            Sequence="10"
            Command="DocumentNewGroup"
            Description=""
            Title="$Resources:core,cui_GrpNew;"
            Image32by32Popup="/_layouts/images/placeholder32x32.png"
            Template="Ribbon.Templates.Flexible2"
          >

 

Ok, on to the next item in our XML, the CommandUIExtensions. They contain the CommandUIDefinitions who are defining the element that you are showing (a Button in our case). The name of the second element escapes me and I can’t check SP2010 at the moment, but the other element within the CommandUIExtensions defines the action of the button (what happens if you click on it) Our little post is only focused on making it appear. Now back to our Button Control.

<Button Id="Ribbon.Documents.New.Controls.MyCoolButton
             Image16by16="/_layouts/images/edit.gif"

             Image32by32="/_layouts/images/placeholder32x32.png"

             Description="MyDescription"

             Command="MyCoolButton"

             LabelText="Banzai"

             Sequence="60"

            TemplateAlias="o1" />

The Id needs to start with Ribbon.Documents.New.Controls. After that you can put whatever you want. The image attributes are used and the images are shown depending on what is defined in the GroupTemplates. What does that mean? In the GroupTemplates (also defined in the CMDGui.xml) it is defined how a button in the ribbon should behave when the page gets resized. Should it hide itself, should it change it’s template (for instance instead of 3 large buttons next to eachother 3 small buttons above eachother)That way we can control how our Ribbon is behaving when the page gets resized. Description is quite easy to understand what it does, Command links to the command that you can define afterwards (you can deploy without having implemented the command), the LabelText is used in the template and shown on the ribbon, the Sequence defines where the button needs to be places and the TemplateAlias links to the template that you are using for that button.

Ok, now that we have that XML we just need to do one more thing:

Add a SharePoint mapped folder to your project and link it to the templates/xml folder. It should automatically create a MyCoolButton folder under the XML folder, but if it doesn’t make sure you do. Add an xml file to it callee MyCoolButton.xml. In that file we will define our link to the javascript files.

<script OnDemandKey="ribbon">
  <File></File>
  <File>SP.Ribbon.js</File>
</script>


Now we are set to go. Rightclick your project, select deploy. Go to a document library, on the ribbon select Documents and you should see a new button next to the New Folder button. (More images will follow as soon as I get home, but we were so excited when it finally worked that I at least had to put it online, but I’m sure Joris will do the same very soon 🙂 )

Should I have missed something, let me know, but this should do the trick for you 🙂

Advertisements
Categories: 2010, Development, Ribbon Tags:
  1. November 5, 2009 at 8:45 pm

    I’ve heard some rumours that Microsoft is developing Ribbon tooling for SharePoint 2010. Maybe it will be included in the RTM?

  2. Daniel
    January 28, 2010 at 6:12 am

    Can you add a button to the Ribbon.List.New group – or any group on a list or calendar page for that matter? I can not for the life of figure out why it isn’t working… Any thoughts?

  3. Raj
    March 22, 2011 at 10:30 am

    Can we hide/disable the button added on the ribbon when a specifc role user i.e.., viewer or contributer logged in?

    in detail……, i added a custom button on ribbon that wil appear when user is at a document library or list. Now i have to check current user belongs to viewer role or contributor role then i have to hide the button that i added on ribbon

    i have to achieve this only by OOB features.

    please help me out.

    regards
    Raj

    • koenvosters
      March 22, 2011 at 2:05 pm

      Didn’t have a lot of time to read through it all, but I think this post will sort your problem: http://sharepointroot.com/2010/06/18/remove-actions-from-the-ribbon-sharepoint-2010/

      • Raj
        March 22, 2011 at 2:17 pm

        Hi koenvosters,

        thank u for ur prompt response.

        I gone thru the URL that u shared. however, it didnt give any solution for my requirement. moreover, i should not use any C# code. I should achieve this only thru OOB i.e., updating xml files in template folder.

        Regards
        Raj

  4. Zakeer
    June 24, 2011 at 7:19 am

    HI,
    Can you say me how can i write a C# code for button click event in the above created custom Feature button.

  1. October 14, 2014 at 11:22 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: