Server Ribbon XML

The following topic describes Server ribbon XML and explains the values that are used for the attributes.

Server Ribbon XML Walkthrough

---

XML

    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition 
          Location="Ribbon.Tabs._children">
          <Tab 
            Id="Ribbon.CustomTabExample" 
            Sequence="501" 
            Description="My New Tab" 
            Title="My New Tab">

The Location on the CommandUIDefinition element defines where the controls inside it will render. In this example, you reference the Tabs collection of the Server ribbon. The _children convention tells the ribbon to insert the following XML into the output for rendering the ribbon. In this case, you are inserting the Tab element XML. The Sequence attribute defines where the tab will render in regards to other tabs. The default tabs use multiples of 100, so the Sequence attribute should not be a multiple of 100 to prevent collisions. Collisions should be avoided to ensure correct handling of the ribbon XML.

XML

            <Scaling
              Id="Ribbon.CustomTabExample.Scaling">
              <MaxSize
                Id="Ribbon.CustomTabExample.MaxSize" 
                GroupId="Ribbon.CustomTabExample.CustomGroupExample" 
                Size="OneLargeTwoMedium"/>
              <Scale 
                Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"
                GroupId="Ribbon.CustomTabExample.CustomGroupExample" 
                Size="OneLargeTwoMedium" />
            </Scaling>

When creating a custom tab, you must define how the tab will scale when controls are added. This is handled by using the Scaling element along with a GroupTemplate. The MaxSize element defines the maximum size of the controls in the group. The Scale element defines how the group will scale in different situations. The GroupId attribute associates a group with the scale size. The Size attribute is defined by the Layout element, which is defined later in this topic.

XML

            <Groups Id="Ribbon.CustomTabExample.Groups">
              <Group 
                Id="Ribbon.CustomTabExample.CustomGroupExample" 
                Description="This is a custom group!" 
                Title="Custom Group" 
                Sequence="52" 
                Template="Ribbon.Templates.CustomTemplateExample">
                <Controls Id="Ribbon.CustomTabExample.CustomGroupExample.Controls">
                  <Button 
                    Id="Ribbon.CustomTabExample.CustomGroupExample.HelloWorld" 
                    Command="CustomTabExample.HelloWorldCommand" 
                    Sequence="15" 
                    Description="Says Hello to the World!" 
                    LabelText="Hello, World!" 
                    TemplateAlias="cust1"/>

The Groups element defines the groups that will appear on the tab. The Group element itself has attributes similar to other controls along with a Template attribute. The Template attribute references the GroupTemplate that is defined later in this topic. The Controls element contains the controls that will render in the group. The acceptable types of controls are defined in Architecture of the Server Ribbon. The controls inside the group must define the TemplateAlias and Command attributes. Like tabs, each control has a Sequence attribute that defines where they will render in the group. The default controls are based on multiples of 10, so any custom controls should not use a multiple of 10 to avoid collisions. The Command attribute is used by the CommandUIHandler element but is required even if the CommandUIHandler is not specified. The TemplateAlias attribute defines where the control will render in relationship to the GroupTemplate.

XML

          <GroupTemplate Id="Ribbon.Templates.CustomTemplateExample">
            <Layout 
              Title="OneLargeTwoMedium" 
              LayoutTitle="OneLargeTwoMedium">
              <Section Alignment="Top" Type="OneRow">
                <Row>
                  <ControlRef DisplayMode="Large" TemplateAlias="cust1" />
                </Row>
              </Section>
              <Section Alignment="Top" Type="TwoRow">
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust2" />
                </Row>
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust3" />
                </Row>
              </Section>
            </Layout>
          </GroupTemplate>

When defining a group template, you must define it another CommandUIDefinition. The CommandUIDefinition has a location of Ribbon.Templates._children. This is the same pattern that is used for groups and tabs.
The GroupTemplate element contains a Layout element that contains Section or OverflowSection elements. The Layout element has a Title attribute that is used for the Size attribute on the MaxSize and Scale elements.
The Section element has two attributes. The Alignment attribute defines where the controls in the following Row elements are positioned. The Type attribute defines the number how many rows will render inside that section. A Section has a maximum of 3 Row elements.
The Row element contains one or more ControlRef elements. Each ControlRef element defines how a single control renders in the ribbon. The DisplayMode attribute has the following values.

Caution
Not all controls have all DisplayMode values available.

Value	Description
Small	Renders as a small icon without label text.
Medium	Renders as a 16 by 16 icon with label text.
Large	Renders as a 32 by 32 icon with label text.
Text	Renders as text only.

You can also have an OverflowSection element instead of a Section element. This element defines an area where multiple controls can render without the need for the Row elements. All controls render the same size defined by the DisplayMode attribute. The DividerAfter and DividerBefore attributes define where the divider appears when the overflow section is rendered.
When adding controls to the default ribbon locations, you should consider the group template and scaling. Adding a control to the default locations can alter the rendering of the group. Most of the default group templates contain overflow sections that grow with your custom controls. In more advanced scenarios, you can override the scaling to render the controls as necessary for your design.

XML

      <CommandUIHandlers>
        <CommandUIHandler 
          Command="CustomTabExample.HelloWorldCommand" 
          CommandAction="javascript:alert('Hello, world!');" />
        <CommandUIHandler 
          Command="CustomTabExample.GoodbyeWorldCommand" 
          CommandAction="javascript:alert('Good-bye, world!');" />
        <CommandUIHandler 
          Command="CustomTabExample.LoveWorldCommand" 
          CommandAction="javascript:alert('I love you, world!');" />
      </CommandUIHandlers>
    </CommandUIExtension>

The CommandUIHandlers element contains all of the CommandUIHandler elements. The CommandUIHandler elements define how controls on the ribbon respond to an action. The Command attribute is a unique name for the command that is used in conjunction with the Command attribute defined with the controls. The CommandAction attribute contains the action that is performed for the control. This can be ECMAScript (JavaScript, JScript), a URL, or anything that was previously contained in an UrlAction element.

XML

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction 
    Id="MyCustomRibbonTab" 
    Location="CommandUI.Ribbon.ListView" 
    RegistrationId="101" 
    RegistrationType="List"> 
    ...
  </CustomAction>
</Elements>

When customizing the ribbon, you use a CustomAction element along with ribbon XML. For more information about custom actions, see Custom Action. The Location attribute tells the CustomAction where to apply the customization. The following table explains the values.

Value	Description
CommandUI.Ribbon	Customization appears everywhere for the specified RegistrationId.
CommandUI.Ribbon.ListView	Customization appears when the list view Web Part is present.
CommandUI.Ribbon.EditForm	Customization appears on the edit form.
CommandUI.Ribbon.NewForm	Customization appears on the new form.
CommandUI.Ribbon.DisplayForm	Customization appears on the display form.

---