ControlRef Element

Last modified: October 13, 2010

Applies to: SharePoint Foundation 2010

In this article
Attributes
Child Elements
Parent Elements
Occurrences
Remarks

Represents a placeholder for a control in a GroupTemplate element.

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

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.

Minimum: 0

Maximum: unbounded

Controls do not necessarily support all display modes. The following table lists the modes that are supported by each type of 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

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>
Show:
© 2014 Microsoft