Yaroslav Pentsarskyy's SharePoint and .NET adventures

This post assumes you already know the basics of building simple ribbon structure. If not, check out this 7 min screencast or this article.

In this post we’ll replace the contents of Elements.XML defining our custom ribbon with something more complex. In essence we’ll create a custom Tab and Group containing only one button.  The result will look somethinglike this and when pressed the button will open a bing.com in a new page:

Here is the contents of Elements.XML, the code is as descriptive as possible and below I will include couple of more explanations to make the code more straightforward:

<?xml version=”1.0″ encoding=”utf-8″?>
<Elements xmlns=”http://schemas.microsoft.com/sharepoint/“>
  <CustomAction
    Id=”MyProject.RibbonButton”
    Location=”CommandUI.Ribbon.ListView”
    RegistrationId=”101″
    RegistrationType=”List”>
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
          Location=”Ribbon.Tabs._children”>
          <Tab
            Id=”MyProject.Ribbon.HelloTab”
            Title=”Custom Tab Title”>
            <Scaling
              Id=”MyProject.Ribbon.HelloTab.Scaling”>
              <MaxSize
                Id=”MyProject.Ribbon.HelloTab.MaxSize”
                GroupId=”MyProject.Ribbon.HelloTab.HelloGroup”
                Size=”OneLargeButton”/>
              <Scale
                Id=”MyProject.Ribbon.HelloTab.Scaling.TabScaling”
                GroupId=”MyProject.Ribbon.HelloTab.HelloGroup”
                Size=”OneLargeButton” />
            </Scaling>
            <Groups Id=”MyProject.Ribbon.HelloTab.Groups”>
              <Group
                Id=”MyProject.Ribbon.HelloTab.HelloGroup”
                Title=”Custom Group Title”
                Template=”MyProject.Ribbon.Templates.HelloTemplate”>
                <Controls Id=”MyProject.Ribbon.HelloTab.HelloGroup.Controls”>
                  <Button
                    Id=”MyProject.Ribbon.HelloTab.HelloGroup.HelloButton”
                    Command=”MyProject.Scripts.HelloCommand”
                    LabelText=”Button Text!”
                    TemplateAlias=”CutomHelloTemplate”/>
                </Controls>
              </Group>
            </Groups>
          </Tab>
        </CommandUIDefinition>
        <CommandUIDefinition Location=”Ribbon.Templates._children”>
          <GroupTemplate Id=”MyProject.Ribbon.Templates.HelloTemplate”>
            <Layout
              Title=”OneLargeButton”
              LayoutTitle=”OneLargeButton”>
              <Section Alignment=”Top” Type=”OneRow”>
                <Row>
                  <ControlRef DisplayMode=”Large” TemplateAlias=”CutomHelloTemplate” />
                </Row>
              </Section>
            </Layout>
          </GroupTemplate>
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
          Command=”MyProject.Scripts.HelloCommand”
          CommandAction=”javascript:window.open(’http://www.bing.com’);” />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
</Elements>
 

1. All of the ID’s in the XML are up to you to name with “whatever” naming conventions are acceptable . Obviously not “&” and other special characters that will break the XML
2. Be consistent with your ID’s since GroupID for example may be used in XML to define it’s look and feel and if you have inconsistencies, you will end up with JavaScript error.
3. All Location values are strict and have to be part of the subset that SharePoint 2010 is expecting, otherwise your controls will not be placed into expected areas (more likely they will not be placed anywhere at all).
4. In our example we attach the ribbon tab to a RegistrationType of a list – you can attach it to the content type as long as your RegistrationId and RegistrationType are defined accordingly.
5. <Tab> defines a tab.
6. <Scaling> defines how your control will render depending if the page is resized. In our example we use the same size. This definition is optional.
7. <Groups> defines groups under the <Tab>
8. <Group> defines individual group under <Groups>
9. Template attribute inside your <Group> will define how your group is layed out. The definition is in <GroupTemplate>.
10. <Controls> will contain your controls , in our case we just use <Button>
11. Command inside your <Button> will carry the name of the command that will execute when the button is clicked. This is later defined in <CommandUIHandler>
12. TemplateAlias contains the name of the template according to which your button will be layed out. Defined in <GroupTemplate><ControlRef>.

As you will see from the example in the earlier article which I referred to, your script doesn’t have to be all on one line, you can define it in a block as a separate CustomAction.

That is it, Enjoy!

Yaroslav Pentsarskyy sharepoint, sharepoint 2010 CommandUIExtension, CommandUIHandler, ribbon, sharepoint 2010, spribbon