Walkthrough: Add a Custom Button to an Existing Group for a Specific Entity

[Applies to: Microsoft Dynamics CRM 2011]

This topic describes how to add a custom button to the Collaborate group of the Account entity. The steps to add a button to any group for a specific entity will be similar.

Tip

A managed solution that includes the goal of this walkthrough is available in the Microsoft Dynamics CRM SDK download at SDK\Walkthroughs\Ribbon\AddaCustomButtontoanExistingGroupforaSpecificEntities.zip.

Because it is a managed solution, you can install (import) it to view the customized ribbon. You can then uninstall (delete) it to remove it from your system.

If you install this managed solution, make sure that you uninstall it before you try the walkthrough steps.

Prerequisites

This walkthrough shows you how to create the following new custom Send to Other System button to the Collaborate group for the Account entity ribbons:

  • Account entity form ribbon

    The customized Account entity form ribbon

  • Account entity grid ribbon

    The customized Account entity grid ribbon

Before you begin, you must have a clear set of requirements. This button:

  1. Will appear only for the Account entity.

  2. Will appear to the right of the Assign button on the account form ribbon Collaborate group.

  3. Will appear to the right of the Assign button on the account grid Collaborate group.

  4. Will appear only in the Web client.

  5. In the account form, this button will only be displayed if the record has been saved.

  6. In the account grid, this button will only be enabled when a single account record is selected.

  7. Will have the label Send to Other System.

  8. Will have a tooltip that displays the label text and the description Sends this Record to another system.

  9. When clicked, the button will display a JScript alert message saying "This record has been sent to another system."

    This message will be displayed using the send function defined in a script Web resource named ‘sample_ SendToOtherSystem.js’.

  10. This button will reference Web resource images to represent the icons.

    The icons will use two Portable Network Graphics (PNG) Web resource images:

    Tip

    You can import the Microsoft Dynamics CRM SDK sample images managed solution to add these icons to your organization. The solution is available in the downloadable files for the SDK at SDK\Walkthroughs\Ribbon\MicrosoftCRMSDKSampleImages.zip.

    Or, you can create your own image Web resources by using the names listed in the following table.

    Icon Name Size
    A 16x16 pixel icon displaying the letter T

    sample_/icons/TIcon16x16.png

    16x16 pixels

    A 32x32 pixel icon displaying the letter T

    sample_/icons/TIcon32x32.png

    32x32 pixels

Procedure to Add a Custom Button to an Existing Group for the Account Entity

Note

These instructions expect that the customization prefix for the current solution publisher is ‘sample’. Unless your solution publisher customization prefix is ‘sample’, or you change your current solution publisher customization prefix to ‘sample’, you must consider that your customization prefix is different. The default customization prefix for the organization publisher is ‘new’.

Export the Account Entity

  1. By exporting and making changes only to the ribbon for the Account entity, you will meet requirement 1.

    You can export the complete default solution, including the Account entity, but to minimize the total file size, we recommend that you create a new solution and add the Account entity to it.

    Tip

    If you add the Account entity to a new solution and the system detects that there are missing required components for the Account entity, you do not have to include them because you will import a modified file back into the same organization.

    To create a new solution and export the ribbon, see Export, Prepare to Edit, and Import the Ribbon

Identify the Ids for Existing Items

  1. Examples of the RibbonXml definitions for entities are available in the SDK download package SDK\Resources\ExportedRibbonXML. The accountRibbon.xml file defines the ribbon for the Account entity. Locate and open this file.

  2. Locate the Collaborate group for the form and the homepage grid.

    • Form Collaborate Group

      <Group Id="Mscrm.Form.account.MainTab.Collaborate"
              Command="Mscrm.Enabled"
              Sequence="40"
              Title="$Resources:Ribbon.HomepageGrid.MainTab.Collaborate"
              Image32by32Popup="/_imgs/ribbon/assign32.png"
              Template="Mscrm.Templates.Flexible2">
        <Controls Id="Mscrm.Form.account.MainTab.Collaborate.Controls">
      
    • HomepageGrid Collaborate group

      <Group Id="Mscrm.HomepageGrid.account.MainTab.Collaborate"
              Command="Mscrm.Enabled"
              Sequence="30"
              Title="$Resources:Ribbon.HomepageGrid.MainTab.Collaborate"
              Image32by32Popup="/_imgs/ribbon/assign32.png"
              Template="Mscrm.Templates.Flexible2">
        <Controls Id="Mscrm.HomepageGrid.account.MainTab.Collaborate.Controls">
      

    You will need to reference this data in later steps. Note the Id values for the Collaborate Group Controls element on both the Form and HomePageGrid tabs.

    The Template attribute value for the Form and homepage Collaborate group is Mscrm.Templates.Flexible2.

    Note the Id attribute value for the Controls element.

  3. In the accountRibbon.xml file, locate the Assign button definition in the Form and homepage Collaborate groups. The requirement is to place the new button to the right of this button; therefore, you must know the Sequence attribute value.

    • Form Assign Button definition

      <Button Id="Mscrm.Form.account.Assign"
              ToolTipTitle="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              ToolTipDescription="$Resources(EntityPluralDisplayName):Ribbon.Tooltip.Assign"
              Command="Mscrm.AssignPrimaryRecord"
              Sequence="32"
              LabelText="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              Alt="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              Image16by16="/_imgs/ribbon/assign16.png"
              Image32by32="/_imgs/ribbon/assign32.png"
              TemplateAlias="o1" />
      
    • HomepageGrid Assign Button definition

      <Button Id="Mscrm.HomepageGrid.account.Assign"
              ToolTipTitle="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              ToolTipDescription="$Resources(EntityPluralDisplayName):Ribbon.Tooltip.Assign"
              Command="Mscrm.AssignSelectedRecord"
              Sequence="40"
              LabelText="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              Alt="$Resources:Ribbon.HomepageGrid.MainTab.Actions.Assign"
              Image16by16="/_imgs/ribbon/assign16.png"
              Image32by32="/_imgs/ribbon/assign32.png"
              TemplateAlias="o1" />
      
  4. For requirement 2, note the sequence value for the Assign button in the form Collaborate group. The value is 32.

  5. For requirement 3, note the sequence value for the Assign button in the grid Collaborate group. The value is 40.

  6. In the accountRibbon.xml file, note the TemplateAlias values for the other controls in the groups. Note that the large buttons use the TemplateAlias ‘o1’ and the smaller buttons use the template alias ‘o2’.

    Locate the definition of the Mscrm.Templates.Flexible2 group template shown in the following example. Notice how the choice of alias affects the size of the buttons for different scales:

    <GroupTemplate Id="Mscrm.Templates.Flexible2">
      <Layout Title="LargeLarge">
        <OverflowSection Type="OneRow"
                          TemplateAlias="o1"
                          DisplayMode="Large" />
        <OverflowSection Type="OneRow"
                          TemplateAlias="o2"
                          DisplayMode="Large" />
        <OverflowSection Type="OneRow"
                          TemplateAlias="isv"
                          DisplayMode="Large" />
      </Layout>
      <Layout Title="LargeMedium">
        <OverflowSection Type="OneRow"
                          TemplateAlias="o1"
                          DisplayMode="Large" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o2"
                          DisplayMode="Medium" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="isv"
                          DisplayMode="Medium" />
      </Layout>
      <Layout Title="MediumMedium">
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o1"
                          DisplayMode="Medium" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o2"
                          DisplayMode="Medium" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="isv"
                          DisplayMode="Medium" />
      </Layout>
      <Layout Title="MediumSmall">
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o1"
                          DisplayMode="Medium" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o2"
                          DisplayMode="Small" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="isv"
                          DisplayMode="Medium" />
      </Layout>
      <Layout Title="LargeSmall">
        <OverflowSection Type="OneRow"
                          TemplateAlias="o1"
                          DisplayMode="Large" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="o2"
                          DisplayMode="Small" />
        <OverflowSection Type="ThreeRow"
                          TemplateAlias="isv"
                          DisplayMode="Small" />
      </Layout>
      <Layout Title="Popup"
              LayoutTitle="LargeMedium" />
    </GroupTemplate>
    

    Because it uses <OverflowSection> (RibbonDiffXml), you can decide to use one of the possible TemplateAlisas values for this <GroupTemplate> (RibbonDiffXml), such as ‘o1’, 'o2' or 'isv'. In this example, you use ‘o1’ so that the button will be larger.

To Create the Script Web Resource

  1. Create a script Web resource named ‘sample_SendToOtherSystem.js’.

  2. Set the source of this Web resource as shown in the following example:

    function send()
    {
       alert("This record has been sent to another system.");
    }
    

In the next step, you configure a <JavaScriptFunction> (RibbonDiffXml) element to use the send function in the sample_SendToOtherSystem.js library.

To Edit the customizations.xml File

  1. Extract the compressed solutions file.

  2. Open the customizations.xml file.

    Tip

    Although you can edit the customization.xml file by using any text editor, we recommend that you use Microsoft Visual Studio or another XML editing application that supports XSD schema validation. This will help avoid XML validation errors when you import the ribbon.

    Associate the customizations.xml file with the customizationsSolution.xsd file. You can find this schema in the SDK\Schemas\CustomizationsSolutions.xsd file in the SDK download package.

    For more information, see Prepare to edit the XML.

  3. Locate the default RibbonDiffXml node shown in the following example:

    <RibbonDiffXml>
      <CustomActions />
      <Templates>
        <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
      </Templates>
      <CommandDefinitions />
      <RuleDefinitions>
        <TabDisplayRules />
        <DisplayRules />
        <EnableRules />
      </RuleDefinitions>
      <LocLabels />
    </RibbonDiffXml>
    
  4. Edit the RuleDefinitions node as shown in the following example to define the display and enable rules to support requirements 4, 5 and 6. For more information, see Define Ribbon Enable Rules and Define Ribbon Display Rules.

    <RuleDefinitions>
      <TabDisplayRules />
      <DisplayRules>
        <DisplayRule Id="Sample.account.form.FormStateNotNew.DisplayRule">
          <FormStateRule State="Create"
                          InvertResult="true" />
        </DisplayRule>
        <DisplayRule Id="Sample.account.WebClient.DisplayRule">
          <CrmClientTypeRule Type="Web"/>
        </DisplayRule>
      </DisplayRules>
      <EnableRules>
        <EnableRule Id="Sample.account.WebClient.EnableRule">
          <CrmClientTypeRule Type="Web" />
        </EnableRule>
        <EnableRule Id="Sample.account.form.NotNew.EnableRule">
          <FormStateRule State="Create"
                          InvertResult="true" />
        </EnableRule>
        <EnableRule Id="Sample.account.grid.OneSelected.EnableRule">
          <SelectionCountRule AppliesTo="SelectedEntity"
                              Maximum="1"
                              Minimum="1" />
        </EnableRule>
      </EnableRules>
    </RuleDefinitions>
    
  5. Edit the LocLabels node as shown in the following example to set the localized labels for requirements 7 and 8. For more information, see Use Localized Labels with Ribbons.

    <LocLabels>
      <LocLabel Id="Sample.account.SendToOtherSystem.LabelText">
        <Titles>
          <Title languagecode="1033"
                  description="Send to Other System" />
        </Titles>
      </LocLabel>
      <LocLabel Id="Sample.account.SendToOtherSystem.ToolTip">
        <Titles>
          <Title languagecode="1033"
                  description="Sends this Record to another system" />
        </Titles>
      </LocLabel>
    </LocLabels>
    
  6. Edit the CommandDefinitions node to add two commands, one for each button for requirement 9. The CommandDefinition consolidates a set of enable rules, display rules, and actions associated with a control. For more information, see Define Ribbon Commands.

    Because the button will be displayed on both the form and the grid, the following example contains separate commands that allow you to clearly define the expected behavior in each location:

    <CommandDefinitions>
      <CommandDefinition Id="Sample.account.form.SendToOtherSystem.Command">
        <EnableRules>
          <EnableRule Id="Sample.account.WebClient.EnableRule" />
          <EnableRule Id="Sample.account.form.NotNew.EnableRule"/>
        </EnableRules>
        <DisplayRules>
          <DisplayRule Id="Sample.account.form.FormStateNotNew.DisplayRule" />
          <DisplayRule Id="Sample.account.WebClient.DisplayRule" />
        </DisplayRules>
        <Actions>
          <JavaScriptFunction Library="$webresource:sample_SendToOtherSystem.js"
                              FunctionName="send" />
        </Actions>
      </CommandDefinition>
      <CommandDefinition Id="Sample.account.grid.SendToOtherSystem.Command">
        <EnableRules>
          <EnableRule Id="Sample.account.WebClient.EnableRule" />
          <EnableRule Id="Sample.account.grid.OneSelected.EnableRule"/>
        </EnableRules>
        <DisplayRules>
          <DisplayRule Id="Sample.account.WebClient.DisplayRule" />
        </DisplayRules>
        <Actions>
          <JavaScriptFunction Library="$webresource:sample_SendToOtherSystem.js"
                              FunctionName="send" />
        </Actions>
      </CommandDefinition>
    </CommandDefinitions>
    
  7. Edit the CustomActions element to add two custom actions, one for each button. Use the Id values that you gathered by using the accountRibbon.xml file to set the Location and Sequence attributes to control where this button will be displayed relative to the other child controls of the Collaborate group. For more information, see Define Custom Actions to Modify the Ribbon.

    As shown in the following example, associate the button to the CommandDefinitions, LocLabels, and Web resource images you created or imported earlier. Also, set the template alias to control how the button is resized in the group template used by the Collaborate group:

    <CustomActions>
      <CustomAction Id="Sample.account.grid.SendToOtherSystem.CustomAction"
                    Location="Mscrm.HomepageGrid.account.MainTab.Collaborate.Controls._children"
                    Sequence="41">
        <CommandUIDefinition>
          <Button Id="Sample.account.grid.SendToOtherSystem.Button"
                  Command="Sample.account.grid.SendToOtherSystem.Command"
                  LabelText="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                  ToolTipTitle="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                  ToolTipDescription="$LocLabels:Sample.account.SendToOtherSystem.ToolTip"
                  TemplateAlias="o1"
                  Image16by16="$webresource:sample_/icons/TIcon16x16.png"
                  Image32by32="$webresource:sample_/icons/TIcon32x32.png" />
        </CommandUIDefinition>
      </CustomAction>
      <CustomAction Id="Sample.account.form.SendToOtherSystem.CustomAction"
                    Location="Mscrm.Form.account.MainTab.Collaborate.Controls._children"
                    Sequence="33">
        <CommandUIDefinition>
          <Button Id="Sample.account.form.SendToOtherSystem.Button"
                  Command="Sample.account.form.SendToOtherSystem.Command"
                  LabelText="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                  ToolTipTitle="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                  ToolTipDescription="$LocLabels:Sample.account.SendToOtherSystem.ToolTip"
                  TemplateAlias="o1"
                  Image16by16="$webresource:sample_/icons/TIcon16x16.png"
                  Image32by32="$webresource:sample_/icons/TIcon32x32.png" />
        </CommandUIDefinition>
      </CustomAction>
    </CustomActions>
    
  8. Your final modified RibbonDiffXml node will look like the following example:

    <RibbonDiffXml>
     <CustomActions>
        <CustomAction Id="Sample.account.grid.SendToOtherSystem.CustomAction"
                      Location="Mscrm.HomepageGrid.account.MainTab.Collaborate.Controls._children"
                      Sequence="41">
          <CommandUIDefinition>
            <Button Id="Sample.account.grid.SendToOtherSystem.Button"
                    Command="Sample.account.grid.SendToOtherSystem.Command"
                    LabelText="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                    ToolTipTitle="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                    ToolTipDescription="$LocLabels:Sample.account.SendToOtherSystem.ToolTip"
                    TemplateAlias="o1"
                    Image16by16="$webresource:sample_/icons/TIcon16x16.png"
                    Image32by32="$webresource:sample_/icons/TIcon32x32.png" />
          </CommandUIDefinition>
        </CustomAction>
        <CustomAction Id="Sample.account.form.SendToOtherSystem.CustomAction"
                      Location="Mscrm.Form.account.MainTab.Collaborate.Controls._children"
                      Sequence="33">
          <CommandUIDefinition>
            <Button Id="Sample.account.form.SendToOtherSystem.Button"
                    Command="Sample.account.form.SendToOtherSystem.Command"
                    LabelText="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                    ToolTipTitle="$LocLabels:Sample.account.SendToOtherSystem.LabelText"
                    ToolTipDescription="$LocLabels:Sample.account.SendToOtherSystem.ToolTip"
                    TemplateAlias="o1"
                    Image16by16="$webresource:sample_/icons/TIcon16x16.png"
                    Image32by32="$webresource:sample_/icons/TIcon32x32.png" />
          </CommandUIDefinition>
        </CustomAction>
      </CustomActions>
      <Templates>
        <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
      </Templates>
      <CommandDefinitions>
        <CommandDefinition Id="Sample.account.grid.SendToOtherSystem.Command">
          <EnableRules>
            <EnableRule Id="Sample.account.WebClient.EnableRule" />
            <EnableRule Id="Sample.account.grid.OneSelected.EnableRule" />
          </EnableRules>
          <DisplayRules>
            <DisplayRule Id="Sample.account.WebClient.DisplayRule" />
          </DisplayRules>
          <Actions>
            <JavaScriptFunction Library="$webresource:sample_SendToOtherSystem.js"
                                FunctionName="send" />
          </Actions>
        </CommandDefinition>
        <CommandDefinition Id="Sample.account.form.SendToOtherSystem.Command">
          <EnableRules>
            <EnableRule Id="Sample.account.WebClient.EnableRule" />
            <EnableRule Id="Sample.account.form.NotNew.EnableRule" />
          </EnableRules>
          <DisplayRules>
            <DisplayRule Id="Sample.account.form.FormStateNotNew.DisplayRule" />
            <DisplayRule Id="Sample.account.WebClient.DisplayRule" />
          </DisplayRules>
          <Actions>
            <JavaScriptFunction Library="$webresource:sample_SendToOtherSystem.js"
                                FunctionName="send" />
          </Actions>
        </CommandDefinition>
      </CommandDefinitions>
      <RuleDefinitions>
        <TabDisplayRules />
        <DisplayRules>
          <DisplayRule Id="Sample.account.form.FormStateNotNew.DisplayRule">
            <FormStateRule State="Create"
                            InvertResult="true" />
          </DisplayRule>
          <DisplayRule Id="Sample.account.WebClient.DisplayRule">
            <CrmClientTypeRule Type="Web" />
          </DisplayRule>
        </DisplayRules>
        <EnableRules>
          <EnableRule Id="Sample.account.WebClient.EnableRule">
            <CrmClientTypeRule Type="Web" />
          </EnableRule>
          <EnableRule Id="Sample.account.form.NotNew.EnableRule">
            <FormStateRule State="Create"
                            InvertResult="true" />
          </EnableRule>
          <EnableRule Id="Sample.account.grid.OneSelected.EnableRule">
            <SelectionCountRule AppliesTo="SelectedEntity"
                                Maximum="1"
                                Minimum="1" />
          </EnableRule>
        </EnableRules>
      </RuleDefinitions>
      <LocLabels>
        <LocLabel Id="Sample.account.SendToOtherSystem.LabelText">
          <Titles>
            <Title languagecode="1033"
                    description="Send to Other System" />
          </Titles>
        </LocLabel>
        <LocLabel Id="Sample.account.SendToOtherSystem.ToolTip">
          <Titles>
            <Title languagecode="1033"
                    description="Sends this Record to another system" />
          </Titles>
        </LocLabel>
      </LocLabels>
    </RibbonDiffXml>
    

Import and Publish the Solution

  1. For more information, see Export, Prepare to Edit, and Import the Ribbon.

Test and Verify that the Requirements Are Met

  1. Open Microsoft Dynamics CRM and view the Accounts sub area of the Navigation Pane.

  2. Verify the following:

    • The Send to Other System button is displayed with the correct label to the right of the Assign button.

    • The Send to Other System button becomes disabled when more than one account record is selected.

    • The expected tooltip text is displayed when you place the pointer over the button.

    • The expected message is displayed when you click the button.

  3. Click the New button to start to create a new account record and confirm that the Send to Other System button is not displayed.

  4. Enter values and save the new account record.

  5. Verify the following:

    • The Send to Other System button is displayed with the correct label to the right of the Assign button.

    • The expected tooltip text is displayed when you place the pointer over the button.

    • The expected message is displayed when you click the button.

See Also

Tasks

Walkthrough: Add a Custom Group to an Existing Tab for a Specific Entity
Walkthrough: Add a Custom Tab to a Specific Entity
Walkthrough: Add a Custom Button to an Existing Group for all Entities
Walkthrough: Hide Ribbon Elements

Other Resources

Ribbon Walkthroughs

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.