Button Element

  • Article

Applies to: SharePoint Foundation 2010

Defines a push button control.

<Button
     Alt="Text"
     Command="Text"
     CommandType="General | OptionSelect | IgnoredByMenu"
     CommandValueId="Text"
     Description="Text"
     Id="Text"
     Image32by32="Url"
     Image32by32Class="CSS Class Selector"
     Image32by32Left="Negative Integer"
     Image32by32Top="Negative Integer"
     Image16by16="Url"
     Image16by16Class="CSS Class Selector"
     Image16by16Left="Negative Integer"
     Image16by16Top="Negative Integer"
     LabelCss="Text"
     LabelText="Text"
     MenuItemId="Text"
     Sequence="Integer"
     TemplateAlias="Text"
     ToolTipImage32by32="Url"
     ToolTipImage32by32Class="Text"
     ToolTipImage32by32Left="Negative Integer"
     ToolTipImage32by32Top="Negative Integer"
     ToolTipTitle="Text"
     ToolTipDescription="Text"
     ToolTipHelpKeyWord="Text"
     ToolTipShortcutKey="Text"
/>

Attributes

Attribute

Description

Alt

Optional. Alternative text for the button.

Command

Optional. The name of the command to execute when the control is clicked. If the control is in a CommandUIDefinition element, the value of the Command attribute of the control should be the same as the value of the Command attribute of a corresponding CommandUIHandler element. The command is used to determine if the control should be enabled or disabled.

CommandType

Optional. An enumeration value that specifies the type of command.

  • General. Not a specific type of command.

  • OptionSelection. A command that is generated when a user selects one option in an option group.

  • IgnoredByMenu. A command that is used for controls that should not close the menu when clicked.

CommandValueId

Optional. A string that is sent with the command event when the button is clicked.

Description

Optional. A string that describes the button. The description is displayed only when the button is in a menu and is being rendered with the Menu32 display mode.

Id

Required. A string that identifies the control, such as "Ribbon.Library.Share.NewRibbonButton".

Image32by32

Optional. A server-relative URL to a file that contains a 32-by-32-pixel image to be used as an icon, such as "/_layouts/1033/images/formatmap32x32.png".

Image32by32Class

Optional. The name of a CSS class selector to be applied to the image.

Image32by32Left

Optional. A negative integer that represents an offset for the left edge of the image. Use this attribute when the Image32by32 attribute points to an image file that contains images for many icons.

The value of the Image32by32Left attribute is used to set the CSS left attribute for the inline style of an HTML img tag. For example, setting the Image32by32Left attribute to "-160" and the Image32by32Top attribute to "-448" results in an inline style that is similar to the one in the following HTML markup:

<img src="/_layouts/1033/images/formatmap32x32.png" style="position: absolute;left: -160px;top: -448px;" />

Image32by32Top

Optional. A negative integer that represents an offset for the top edge of the image. Use this attribute when the Image32by32 attribute points to an image file that contains the images for many icons. The value of the Image32by32Top attribute is used to set the CSS top attribute for the inline style of an HTML img tag.

Image16by16

Optional. A server-relative URL to a file that contains a 16-by-16-pixel image to be used as an icon, such as "/_layouts/1033/images/formatmap16x16.png".

Image16by16Class

Optional. The name of a CSS class selector to be applied to the image.

Image16by16Left

Optional. A negative integer that represents an offset for the left edge of the image. Use this attribute when the Image16by16 attribute points to an image file that contains images for many icons. The value of the Image16by16Left attribute is used to set the CSS left attribute for the inline style of an HTML img tag.

Image16by16Top

Optional. A negative integer that represents an offset for the top edge of the image. Use this attribute when the Image16by16 attribute points to an image file that contains images for many icons. The value of the Image16by16Top attribute is used to set the CSS top attribute for the inline style of an HTML img tag.

LabelCss

Optional. The name of a CSS class selector to be applied to the control's label.

LabelText

Optional. The text to label the control.

MenuItemId

Optional. A string that identifies the menu item where the button is located.

Sequence

Optional. An integer that specifies the order of placement among sibling XML nodes.

TemplateAlias

Optional. A string that matches the value of the TemplateAlias attribute for a ControlRef element, an OverflowArea element, or an OverflowSection element in a GroupTemplate element. The TemplateAlias attribute is used to size and position controls within a group when a template is applied to the group.

ToolTipImage32by32

Optional. A server-relative URL to a file that contains a 32-by-32-pixel image to be used in the tooltip, such as "/_layouts/1033/images/formatmap32x32.png".

ToolTipImage32by32Class

Optional. The name of a CSS class selector to be applied to the image.

ToolTipImage32by32Left

Optional. A negative integer that represents an offset for the left edge of the image. Use this attribute when the ToolTipImage32by32 attribute points to an image file that contains the images for many icons. The value of the ToolTipImage32by32Left attribute is used to set the CSS left attribute when the page is created.

ToolTipImage32by32Top

Optional. A negative integer that represents an offset for the top edge of the image. Use this attribute when the ToolTipImage32by32 attribute points to an image file that contains the images for many icons. The value of the ToolTipImage32by32Top attribute is used to set the CSS top attribute when the page is created.

ToolTipTitle

Optional. The text that appears as the title of the tooltip.

ToolTipDescription

Optional. The text that appears in the body of the tooltip.

ToolTipHelpKeyWord

Optional. The keyword that is used by context-sensitive Help.

ToolTipShortcutKey

Optional. The text to display for the shortcut key in the tooltip. For example, if the shortcut key for the control is ALT + J, the value for this attribute is "ALT + J". The tooltip will display the text for the shortcut key in parentheses after the tooltip title: "(ALT + J)".

Child Elements

None

Parent Elements

CommandUIDefinition

Controls (Group)

Controls (MenuSection)

Occurrences

Minimum: 0

Maximum: unbounded

Example

The following example shows how to add a button control to the Server ribbon. The example adds a "Help" button to the ribbon in the same group as the built-in New Document, New Folder, and Upload Document controls:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Id="NewUIRibbonControl"
    RegistrationType="List"
    RegistrationId="101"
    Location="CommandUI.Ribbon">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
           Location="Ribbon.Documents.New.Controls._children">
          <Button
             Id="NewUIRibbonControl.ShowHelp"
             Alt="Help"
             Sequence="1981"
             Command="ShowHelp"
             Image32by32="/_layouts/images/newui/dochelp.png"
             LabelText="Help"
             TemplateAlias="o1"/>
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
         Command="ShowHelp"
         CommandAction="javascript:window.open('https://msdn.microsoft.com/en-us/library/ee539395%28office.14%29.aspx');" />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
</Elements>

See Also

Tasks

Walkthrough: Adding a Button to the Server Ribbon