The <CommandUIDefinitions> tag can contain one or more <CommandUIDefinition> tags. Each <CommandUIDefinition> tag defines one ribbon control. Some of values of the attributes of the <CommandUIDefinition> tag are similar to those used to define a custom action in SharePoint Designer. For example, the Location attribute specifies the tab and group of the control in dot-separated notation, as used in the Ribbon Location text box of the Create A Custom Action dialog box. The value of the Id attribute can be anything; however, the convention is to mimic the dot-separated notation of the Location attribute.

In the code that follows, a new button control is defined on the display form of a list. Referring to Table 15-1, using a sequence number of 25 instructs SharePoint to place the control between the Check Out and Alert Me controls:

<CommandUIDefinition Location="Ribbon.ListForm.Display.Controls._children">
  <Button Id="Ribbon.List.Display.SPFIONewControl"
      Sequence="25"
      Command="SPFIONewCommand"
      Description="SPFIO New Control"
      LabelText="New SPFIO Control"
      Image32by32="~sitecollection/SiteAssets/SPFIO32x32.gif"
      Image16by16="~sitecollection/SiteAssets/SPFIO16x16.gif"
      TemplateAlias="o1"
      ToolTipTitle="SPFIO New Control Tool Tip"
      ToolTipDescription="SPFIO Tool Tip Description"
      ToolTipShortcutKey="Ctr-T,E"
      ToolTipImage32by32="~sitecollection/SiteAssets/SPFIO32x32.gif"
      ToolTipHelpKeyWord="SPFIO"
   />
</CommandUIDefinition>

The TemplateAlias attribute instructs SharePoint where in the group template to place the image for this control. A number of templates are predefined in the CMDUI.XML file. Microsoft recommends that you create your own, especially when creating your own tabs, because the templates from the CMDUI.XML file might not be loaded when your tab is displayed. To define a new template, use the <CommandUIDefinition> tag with a location of Ribbon.Templates._children and a child tag of <GroupTemplate>.

To replace a ribbon control, use the <CommandUIDefinition> tag, and on the Location attribute, specify the name of the control. In the code example that follows, the New Folder control in the New group on the Documents tab is replaced with a different icon and calls the SPFIOExScriptBlock command defined in the <CommandUIHandler> tag. For SharePoint to overwrite the existing New Folder control, the sequence number must be lower than the out-of-the-box sequence number for that control. You can find this number by referring to the CMDUI.XML file. If you and other developers have created many custom actions for the same control, then the lowest sequence number will win:

<CommandUIDefinition Location="Ribbon.Documents.New.NewFolder">
   <Button Id="Ribbon.Documents.New.NewFolder.SPFIOFolderButton"
      Alt="SPF New Folder control"
      Sequence="5"
      Command="SPFIOExScriptBlock"
      LabelText="SPFIO New Folder"
      Image32by32="~site/SiteAssets/SPFIO32x32.gif"
      TemplateAlias="o1" />
</CommandUIDefinition>

The following code is an example of a custom action that adds a group and a button to the ribbon of Web Part pages:

<CustomAction Id="SPFIO.WebPage" Location="CommandUI.Ribbon">
   <CommandUIExtension>
      <CommandUIDefinitions>
         <CommandUIDefinition Location="Ribbon.WebPartPage.Groups._children">
            <Group Id="Ribbon.WebPartPage.SPFUI.WebPart"
               Sequence="20" Description="SPFIO Ribbon group"
               Title="SEF Group" Template="Ribbon.Templates.Flexible2">
               <Controls Id="Ribbon.WebPartPage.SPFIO.WebPart.Controls">
                  <Button Id="Ribbon.WebPartPage.SPFIO.WebPart.Command"
                     Command= "SPFIOExScriptBlock"
                     Description="SEF Custom action"
                     Image16by16="~sitecollection/SiteAssets/SPFIO16x16.gif"
                     Image32by32="~sitecollection/SiteAssets/SPFIO32x32.gif"
                     LabelText="SEF Action"
                     TemplateAlias="o2"
                     Sequence="35" />
               </Controls>
            </Group>
         </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
         <!-see next section ->
      </CommandUIHandlers>
   </CommandUIExtension>
</CustomAction>

When this control is clicked, the command that is defined in the <CommandUIHandler> tag, which has a command named SPFIONewCommand, is executed.

Tip

INSIDE OUT Using the out-of-the-box images with your custom actions

For consistency, when your control executes an action, similar to an existing control, you might want to use the same icon to represent your new custom action. Many of these images are in the SharePoint root folder in the TEMPLATEIMAGES subfolder. To quickly find the image file that’s used, in Microsoft Internet Explorer (IE), open the page on which the icon is displayed, and then press F12 to open the IE developer tools. On the HTML tab, click the pointer, and then on the page, select the relevant image.

Not all out-of-the-box ribbon images are stored in their own file, and therefore, you might see code similar to the following:

<img style="left: -80px; top: -176px; " alt=""
  src="/_layouts/1033/format16x16.png" unselectable="on" />

SharePoint 2010 uses special image files—formatmap32x32.png and format16x16.png—which contain a collection of images, as shown in Figure 15-13. These files are stored in the SharePoint root, in the subfolder TEMPLATELAYOUTS[LCID]IMAGES.

Figure 15-13. Use images from the format32x32.png or format16x16.png for your controls.

You can refer to images from these two files in your action controls by using the Image32by32Top and Image32by32Left attributes when you use the Image32by32 attribute or the equivalent attributes for a 16×16-pixel image.

The top and left attributes identify the upper-left corner of an image in the image map and are used to set the CSS top and left attributes for the inline style of an HTML <IMG> tag. To calculate the upper-left corner of an image, open the image in Microsoft Paint, display the status bar, and then place the cursor on the upper-left corner of the desired image. In the format32x32.png file, the upper-left coordinate is a multiple of 32, and in the format16x16.png file, the upper-left coordinate is a multiple of 16. This number represents the offset from the upper-left corner of the image map and is a negative number.

For example, the image used for the New Quick Step command can be found in the second column and eleventh row of the format32x32.png file, and whose coordinates would be –32, –320. In a custom action this image would be referred as:

Image32by32="_layouts/1033/images/formatmap32x32.png"
      Image32by32Top="-32" Image32by32Left="-320"

The <CommandUIHandlers> tag can contain one or more <CommandUIHandler> tags. The value of the Command attribute of the <CommandUIHandler> tag has the same name as the value of the Command attribute in the <CommandUIDefinition> tag.

Each <CommandUIHandler> tag defines one command, written by using ECMAScript, which is the scripting language (such as JavaScript and Jscript) that is commonly used for client-side scripting; that is, code that is parsed and executed by the browser. There are two types of commands that you can use:

Both types of commands are targeted by using the <CommandUIHandler> tag. The code that follows contains three examples of UI handlers. The first contains the JavaScript within the <CommandUIHandler> tag, the second calls a script block defined in a <CustomAction> tag, and the third displays a page when a control is clicked:

<CommandUIHandler Command="SPFIONewCommand"
   CommandAction="javascript:alert('SPFIO New Display Form Control Clicked!'),"
/>

<CommandUIHandler Command="SPFIOExScriptBlock"
   CommandAction="javascript:SPFIOCode();"
/>

<CommandUIHandler Command="SPFIONavSiteSettings"
   CommandAction="/_layouts/settings.aspx"
/>

The <CustomAction> section that defines the script block inline would look similar to the following code:

<CustomAction Id="Ribbon.ListForm.Display.NewButton.Script"
   Location="ScriptLink"
   ScriptBlock="
      function SPFIOCode()
      {
         alert('SPFIO Ribbon Script Block'),
      }"
/>

Use the ScriptBlock method to quickly insert short amounts of code, which will be merged into the page with other JavaScript that is included by using the <link> tag. If your code is large or needs to be referenced by a number of custom action solutions, you should place your JavaScript code in one file, and then use a custom action to reference the file, as shown in the following code:

<CustomAction Id="Ribbon.ListForm.Display.Script"
   Location="ScriptLink"
   Scrptsrc="~site/SiteAssets/SPFIO_RibbonControls.js" />