The first control in the SharePoint 2010 Ribbon Controls series (full series index available here) will be about the Label control.

What is the Label control?

The Label control is a simple control that allows you to add a Label to any of your Ribbon groups. Labels are most often used in combination with other controls such as text boxes and drop downs. You can using a label target another control so that if you click on the label then the other control gets focus. A Label can be a text, an icon or both.

Label Controls

As the image above shows Labels can have three forms:

  1. Just a text label
  2. A text label with an icon
  3. Just an icon

Sample Label control

This is how a Label control could be defined:

Label 
  Id="Wictor.RibbonControls.Tab.Label"
  LabelText="Label Text"
  Image16by16="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
  Image16by16Left="0"
  Image16by16Top="-32"
  Image16by16Class="LabelClass"    
  TemplateAlias="section2"
  ForId="Wictor.RibbonControls.Tab.TextBox"
  Command="Wictor.RibbonControls.LabelComand"
  QueryCommand="Wictor.RibbonControls.LabelQueryCommand"
  Sequence="10"/>

Label control properties

The Label control have a few properties worth noticing, except the common ones.

Property: LabelText

The LabelText property is the text that is displayed in the label.

Property: Image16by16, Image16by16Top, Image16by16Left, Image16by16Class

A Label can have one16x16 pixel sized icon and/or CSS class.

Property: TemplateAlias

The TemplateAlias (one of the common properties) must be configured so that is connected to a section in the Group Template that has the DisplayMode of either Medium or Small. Any other Display Modes will cause your Ribbon customization to fail. The LabelText, TemplateAlias and icon determines the layout of the Label:

  • A Small DisplayMode must have an icon and will only show the icon (only text on a small Label will cause an error). Label #3 in the image above
  • A Medium sized icon must have a LabelText and optionally an icon. Label #1 and #2 in the image above.

Property: ForId

The ForId property is the Id of another Ribbon control. When the Label is selected the control specified by the ForId will get focus.

Property: Command

The Command property is never used by the Label control.

Property: QueryCommand

The QueryCommand property invokes the command when the Tab containing the control receives focus. This can be used to dynamically update the value of the LabelText. In a JavaScript Page Component you update the LabelText as follows, if the QueryCommand has the value of ‘Wictor.RibbonControls.LabelQueryCommand’:

handleCommand: function (commandId, properties, sequence) {
    switch (commandId) {
        case 'Wictor.RibbonControls.LabelQueryCommand':
            properties['Value'] = 'Label changed';
            return;
    }
}

When the Tab receives focus the Label will change its LabelText to the value specified in the JavaScript.

Summary

That was the first one - the Label control. Next time we’ll add a TextBox which will be connected to the Label using the ForId property.