SharePoint 2010 Ribbon customization : Basics

This article is the first of a series of articles intended to address a real-world ribbon customization requirement. In this article, we will look at the basic architecture of the Ribbon in Sharepoint 2010.
To see ribbon’s internal you need to look into CMDUI.xml file, which you can find at location 14\template\global\xml\cmdui.xml.
But it is too confusing right now.. so the best way to look at it is look at the hierarcy of Ribbon. It starts with the base Ribbon implementation which is something like this
Ribbon > Tabs > Groups > Controls
A ribbon can have mutiple tabs, each tab mutiple groups and each assemble multiple controls. These controls can be a Button, CheckBox, Dropdown etc. The complete list is here ..
We will start with a hello world example and then build functionlity. We are not going to make a custom tab or assemble, but just add a button first to an existing location. It is better to know this way.
Not more than is a shot of the xml that will add a new button..

Description of some of the elements in the screenshot above..

  1. this will determine where the new item to be made will reside.. whether is the ribbon or the ECB ( thats the contextual dropdown on the list item) or the Site Actions Menu or on the Backup & Restore page in central admin or whereever; this will choose where it is to be made. Here is a list of all possible locations . The ones we are attracted are..

    • CommandUI.Ribbon.ListView
    • CommandUI.Ribbon.NewForm
    • CommandUI.Ribbon.EditForm
    • CommandUI.Ribbon.DisplayForm
    • CommandUI.Ribbon
    if you dont know where exactly you want it to be place except for the fact that it should be a ribbon.. then select ‘CommandUI.Ribbon’
  2. This is the most vital entry you will be making. This will determine where in the ribbon will it show up. As already mentioned, we just want to add a button. But as per the hierarchy, the button is a control and its parent is a assemble. So you will have to find the appropriate assemble name add your button.. but how ?

    As an example, we want the button available for a document, under the Manage assemble

    Here is a list of all possible locations you can choose from. It lists the groups and the controls that are in each assemble. You are attracted in the assemble, so search for a assemble that matches close to the assemble name “Manage” and also should be present in a tab named “Document”. Here you go the assemble name location “Ribbon.ID.Manage”

    Now, since you got your groupname.. you have to specify that you are going to add a child control.. the syntax is “Controls._children”. Hence your complete location is “Ribbon.ID.Manage.Controls._children”

    The sequence also place a role where it is placed within the assemble.

  3. This is just a name to the new control, in this case a button. Typically I take the assemble name “Ribbon.ID.Manage” and prefix this with the company name I am rising this for “ManoInc” and postfix with a unique button name “HelloWorld” .
  4. This is the command that is do when the button is clicked. Again, you can be innovative in giving a name. Make sure you use the same name defining the command the “CommandUIHandler section
  5. This is the image that is rendered for the button that you have defined.

    Note that I have used the OOTB image in this case that is “formatmap32x32.png”. This is a special image where it a collection of images in one image. when you use this image or any other image where there is collection of image in a single file, you have to use the Image32by32Top and the Left attributes to render by the book.

    Basically, A negative integer representing an offset for the left edge of the image. Use this attribute when the Image32by32 attribute points to an image file that contains images for many icons.

    The value of the Image32by32Left attribute is used to set the CSS left attribute for the inline style of an HTML img tag. For example, setting the Image32by32Left attribute to “-160″ and the Image32by32Top attribute to “-448″ consequences in an inline style that is similar to the one in the following HTML markup:

    A simple way to calculate this co-ordinates is notch the image in MS Paint and place you cursor on the corner of the image you want. If you look at the bottom left of the MSPaint, you will see the co-ordinates e.g 259, 127px. This value is the left and the top co-ordinate of the image. All images in this file are 32x32px. if you caluclate a multiple of 32, the nearest value of 259 is 256 and the nearest to 127 is 128. Here you have it, the Image32by32Left = 256 and Image32by32Top = 128

Build your ‘Hello World’ Ribbon
Now that you know the basics, lets build the feature and install and test it..
1. Make a new sharepoint machinate in VS 2010. Make sure you specify the proper Url for this to install and make note of this url.

2. Add a new item of the type “Empty Element” to the machinate.

3. Add the following xml in the elements file

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="DocFinalRibbon" Location="CommandUI.Ribbon">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.ID.Manage.Controls._children">
          <Button
            Id="ManoInc.Ribbon.ID.Manage.HelloWorld"
            Sequence="40"
            Command="ManoInc.Ribbon.ID.Manage.HelloWorld.cmdSayHelloWorld"
            Image16by16="/_layouts/1033/images/formatmap16x16.png" Image16by16Top="-144" Image16by16Left="0"
            Image32by32="/_layouts/1033/images/formatmap32x32.png" Image32by32Top="-128" Image32by32Left="-256"
            LabelText="Hello World"
            ToolTipTitle="Click button to prompt 'Hello World'"
            ToolTipDescription="Once you click this button, you will get a hello world dialog box "
            TemplateAlias="o1"/>
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
          Command="ManoInc.Ribbon.ID.Manage.HelloWorld.cmdSayHelloWorld"
          CommandAction="javascript:alert('Hi Mano');" />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
</Elements>

4. Hit F5 to install. Navigate to a document libary, click on the document tab and there you have it, your Ribbon button.

Check it out:SharePoint 2010