ControlRef element (Server Ribbon)

Applies to: SharePoint 2016 | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

Represents a placeholder for a control in a GroupTemplate element.

<ControlRef
  DisplayMode="Small | Medium | Large | Menu | Menu16 | Menu32"
  TemplateAlias="Text"
/>

Elements and attributes

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
DisplayMode	Optional. An enumeration value that determines how a control is rendered: - Small. Renders as a small icon without label text. - Medium. Renders as a 16-by-16-pixel icon with label text. - Large. Renders as a 32-by-32-pixel icon with label text. - Menu. Renders as a text-only menu item. - Menu16. Renders as a menu item with a 16-by-16-pixel icon. - Menu32. Renders as a menu item with a 32-by-32-pixel icon.
TemplateAlias	Optional. A string that a control can reference in its own TemplateAlias attribute. The TemplateAlias attribute is used to size and position controls in a group when a template is applied to the group. No two elements that are contained by the same GroupTemplate element should have the same TemplateAlias value.

Child elements

None

Parent elements

• Row
• Strip

Occurrences

• Minimum: 0
• Maximum: unbounded

Remarks

Controls do not necessarily support all display modes. The following table lists the modes that are supported by each type of control.

Control	Small	Medium	Large	Menu	Menu16	Menu32
Button	X	X	X	X	X	X
CheckBox	X	X
ColorPicker				X
ComboBox		X
DropDown		X
FlyoutAnchor	X	X	X	X	X	X
GalleryButton			X	X
InsertTable				X
Label	X	X
MenuSection					X	X
MRUSplitButton	X	X	X
Spinner		X
SplitButton	X	X	X
TextBox		X
ToggleButton	X	X	X

Example

The following example is an XML fragment that shows the relationship between the TemplateAlias attribute for controls in a Group element and the same attribute for ControlRef elements in a GroupTemplate element.

Notice that the Group element contains three Button elements, each with a TemplateAlias attribute set to a value of "row1", "row2", or "row3".

The GroupTemplate element also contains three ControlRef elements that have attributes set to a value of "row1", "row2", or "row3".

When the template is applied to the group, the layout of the controls in the group is determined by matching the TemplateAlias attribute of a Button element to the TemplateAlias attribute of a ControlRef element.

<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!"
      TemplateAlias="row1"/>
    <Button
      Id="Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"
      Command="CustomTabExample.GoodbyeWorldCommand"
      Sequence="17"
      Description="Says goodbye to the World!"
      LabelText="Goodbye!"
      TemplateAlias="row2"/>
    <Button
      Id="Ribbon.CustomTabExample.CustomGroupExample.LaterWorld"
      Command="CustomTabExample.LaterWorldCommand"
      Sequence="19"
      Description="Says I will see you later to the World!"
      LabelText="Later!"
      TemplateAlias="row3"/>
  </Controls>
</Group>
<GroupTemplate Id="Ribbon.Templates.CustomTemplateExample">
  <Layout
    Title="OneLargeTwoMedium"
    LayoutTitle="OneLargeTwoMedium">
    <Section Alignment="Top" Type="OneRow">
      <Row>
        <ControlRef DisplayMode="Large" TemplateAlias="row1" />
      </Row>
    </Section>
    <Section Alignment="Top" Type="TwoRow">
      <Row>
        <ControlRef DisplayMode="Medium" TemplateAlias="row2" />
      </Row>
      <Row>
        <ControlRef DisplayMode="Medium" TemplateAlias="row3" />
      </Row>
    </Section>
  </Layout>
</GroupTemplate>