Walkthrough: Add a Custom Button to an Existing Group for all Entities

  • Article

[Applies to: Microsoft Dynamics CRM 2011]

This topic describes how to add a custom button to the form ribbon Save group for all entities. This example adds a Close button to each of the entities that include the Save group.

Tip

A managed solution that includes the goal of this walkthrough is available in the Microsoft Dynamics CRM SDK download at SDK\Walkthroughs\Ribbon\AddaCustomButtontoanExistingGroupforallEntities.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 you uninstall it before you try the walkthrough steps.

Prerequisites

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

  1. Will appear for all entities that use the default Save group defined for entities.

  2. Will appear in the Save group of the form ribbon only. The grid ribbon does not have a Save group.

  3. Will be displayed directly below the Delete button.

  4. Will have the label Close.

  5. Will have a tooltip that displays the label text and the description "Close this window."

  6. When clicked, the button will close the window immediately if the user has not changed any data in the form. If data has been changed, the user will be shown a dialog box and asked if the user wants to save or discard the changes.

  7. Will reference Web resource images to represent the icons.

    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 in the following list.

    • A 16x16 pixel PNG file with the Web resource name 'Sample_/icons/Close16.png'.

    • A 32x32 pixel PNG file with the Web resource name 'Sample_/icons/Close32.png'.

The final custom button will appear for all entities, such as the following screenshot that shows the Lead entity.

A custom Close button appears in the Save group.

Export the Application Ribbons

  • You may export the entire default solution, including the application ribbons, but in order to minimize the total file size, we recommend that you create a new solution and add the application ribbons entity to it.

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

Identify the Ids for Existing Items

  1. Use the applicationRibbon.xml file in the SDK download package at SDK\Resources\ExportedRibbonXml to identify the form Save group for all entities. You should familiarize yourself with the default configuration because your customization will refer to elements found there.

    The Id values for the Save group controls element are Mscrm.Form.{!EntityLogicalName}.MainTab.Save.Controls.

  2. Examine the group template used by the Save group. Make a note that it is 'Mscrm.Templates.3.3'.

  3. The other controls in the Save group use the template aliases o1 and o2. The template alias ‘isv’ is available.

Create a Script Web Resource

  • Create a script Web resource named ‘sample_/scripts/formActions.js’ with the following content:

    function closeForm() 
{
   Xrm.Page.ui.close();
}

    Note

    The window.close method a Web developer would normally use is suppressed in the form. It will not succeed and it will not throw an error. Use Xrm.Page.ui.close to close the window.

Edit the customizations.xml File

  1. Extract the compressed solutions file.

  2. Open the customizations.xml file.

    Tip

    Although it is possible to edit the customization.xml file by using any text editor, it is highly recommended 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\CustomizationsSolution.xsd file in the SDK download package.

    For more information, see Prepare to edit the XML.

  3. Locate the default RibbonDiffXml node:

    <RibbonDiffXml>
 <CustomActions />
 <Templates>
  <RibbonTemplates Id="Mscrm.Templates">
  </RibbonTemplates>
 </Templates>
 <CommandDefinitions />
 <RuleDefinitions>
  <TabDisplayRules />
  <DisplayRules />
  <EnableRules />
 </RuleDefinitions>
 <LocLabels />
</RibbonDiffXml>

  4. Edit the <LocLabels> (RibbonDiffXml) node to set the localizable text for the button label and tooltip:

    <LocLabels>
 <LocLabel Id="Sample.all.Close.LabelText">
  <Titles>
   <Title languagecode="1033"
          description="Close" />
  </Titles>
 </LocLabel>
 <LocLabel Id="Sample.all.Close.ToolTip">
  <Titles>
   <Title languagecode="1033"
          description="Close this window." />
  </Titles>
 </LocLabel>
</LocLabels>

  5. Add the following in the <CommandDefinitions> (RibbonDiffXml) element:

    <CommandDefinitions>
  <CommandDefinition Id="Sample.form.Close">
    <EnableRules />
    <DisplayRules />
    <Actions>
      <JavaScriptFunction FunctionName="closeForm"
                          Library="$webresource:sample_/scripts/formActions.js" />
    </Actions>
  </CommandDefinition>
</CommandDefinitions>

  6. Edit the CustomActions element to add a custom action for the form. Use the Id values you gathered using the applicationRibbon.xml file to set the CustomAction.Location attribute value to Mscrm.Form.{!EntityLogicalName}.MainTab.Save.Controls._children. Set the Button.Id attribute value to 'Sample.{!EntityLogicalName}.form.Close.Button'.

    Note

    Using the {!EntityLogicalName} token in the control Id and the custom action location will cause this custom action to be applied to all entities, and the control will also be defined for all entities. For example, for the Account entity, the button can be referenced as Sample.account.form.Close.Button. This can be useful if you want to apply a hide custom action to remove the button for specific entities.

    Associate the button to the Sample.form.Close command, the labels, and Web resource images. Also set the button TemplateAlias attribute value to o2.

    <CustomActions>
  <CustomAction Id="Sample.all.form.Close.CustomAction"
                Location="Mscrm.Form.{!EntityLogicalName}.MainTab.Save.Controls._children"
                Sequence="75">
    <CommandUIDefinition>
      <Button Id="Sample.{!EntityLogicalName}.form.Close.Button"
              Command="Sample.form.Close"
              LabelText="$LocLabels:Sample.all.Close.LabelText"
              ToolTipTitle="$LocLabels:Sample.all.Close.LabelText"
              ToolTipDescription="$LocLabels:Sample.all.Close.ToolTip"
              TemplateAlias="o2"
              Image16by16="$webresource:Sample_/icons/Close16.png"
              Image32by32="$webresource:Sample_/icons/Close32.png" />
    </CommandUIDefinition>
  </CustomAction>
</CustomActions>

  7. Your final modified RibbonDiffXml node should look like this:

    <RibbonDiffXml>
  <CustomActions>
    <CustomAction Id="Sample.all.form.Close.CustomAction"
                  Location="Mscrm.Form.{!EntityLogicalName}.MainTab.Save.Controls._children"
                  Sequence="75">
      <CommandUIDefinition>
        <Button Id="Sample.{!EntityLogicalName}.form.Close.Button"
                Command="Sample.form.Close"
                LabelText="$LocLabels:Sample.all.Close.LabelText"
                ToolTipTitle="$LocLabels:Sample.all.Close.LabelText"
                ToolTipDescription="$LocLabels:Sample.all.Close.ToolTip"
                TemplateAlias="o2"
                Image16by16="$webresource:Sample_/icons/Close16.png"
                Image32by32="$webresource:Sample_/icons/Close32.png" />
      </CommandUIDefinition>
    </CustomAction>
  </CustomActions>
  <Templates>
    <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
  </Templates>
  <CommandDefinitions>
    <CommandDefinition Id="Sample.form.Close">
      <EnableRules />
      <DisplayRules />
      <Actions>
        <JavaScriptFunction FunctionName="closeForm"
                            Library="$webresource:sample_/scripts/formActions.js" />
      </Actions>
    </CommandDefinition>
  </CommandDefinitions>
  <RuleDefinitions>
    <TabDisplayRules />
    <DisplayRules />
    <EnableRules />
  </RuleDefinitions>
  <LocLabels>
    <LocLabel Id="Sample.all.Close.LabelText">
      <Titles>
        <Title languagecode="1033"
                description="Close" />
      </Titles>
    </LocLabel>
    <LocLabel Id="Sample.all.Close.ToolTip">
      <Titles>
        <Title languagecode="1033"
                description="Close this window." />
      </Titles>
    </LocLabel>
  </LocLabels>
</RibbonDiffXml>

Import and Publish the Solution

Test and Verify that the Requirements Are Met

  1. Open Microsoft Dynamics CRM and view the form for any entity.

  2. Verify the following:

    • The Close button appears below the Save and New button in the Save area.

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

    • When the button is pressed, if the form data has not been changed, the window closes. When the form data has been changed, a dialog box appears that provides options about how to deal with unsaved changes.

See Also

Tasks

Walkthrough: Add a Custom Button to an Existing Group for a Specific Entity
Walkthrough: Add a Custom Group to an Existing Tab for a Specific Entity
Walkthrough: Add a Custom Tab to a Specific Entity
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.