CRM – adding a custom button to the form ribbon

Posted on

 

Here’s a quick guide to adding a custom button to ribbon on a form in Microsoft Dynamics CRM 2011 and 2013.

In this example, we will be adding a button to the Account form to launch a custom Dialog.

 

 

 

 

 

Getting the Customizations XML

To get the customizations xml we need to follow a few short steps.

  1. Create a Solution in CRM and add the Account entity.
  2. Export the solution and then delete the solution from CRM.
  3. Unzip the exported solution and then open the customizations.xml file in your preferred text editor.
  4. Locate the <RibbonDiffXml> tag of the Account entity. This is where we will be making our changes.

Adding a Custom Action

The first thing we should do is define the new button including properties such as which ribbon tab it will appear on and what size the button will be.

In the <CustomActions> tag we need to add a new custom action with a new command UI definition as shown below.

       <CustomActions>

             <CustomAction Id=”CI_formlevelOpenDialog”  

             Location=”Mscrm.Form.account.MainTab.Actions.Controls._children” 

             Sequence=”151″>

                       <CommandUIDefinition>

                       <Button Id=”B_newformbutton”

                        Command=”Cmd_OpenNewDialog”

                        LabelText=”Open Dialog”

                        ToolTipTitle=”Open New Dialog”

                        ToolTipDescription=”Open from this custom ribbon button”

                        TemplateAlias=”o1″ Image16by16=”$webresource:new_buttonimage16x16″

                        Image32by32=”$webresource:new_buttonimage32x32″ />

             </CommandUIDefinition>

          </CustomAction>       

     </CustomActions>

 

We should give a meaningful identifier to the button and to the command it will action (we will be defining the command in the next section). We should also provide the button with a label and tool tip text.

 

Note: In Dynamics CRM 2011 The Template Alias we give the button will define the arrangement of the button. Using the default template, “o1” will fit the button to the size of the column (like Assign) and “o2” will fit the button to the size of a third of a column (like Sharing). The ribbon layout of Dynamics CRM 2013 is much flatter so this element can be omitted.

Paul 1

 

 

We also need to set the button icons for 16×16 and 32×32 sizes from PNG web resources in CRM. We can easily add these to the default solution in a few steps.

  • Open the default solution in CRM and click on “Web Resources”.
  • Click the “New” button.
  • Give the new resource a meaningful name. It’s a good idea to include the size of the icon in the name (e.g. new_buttonimage16x16).
  • Set the Type as “PNG format” and choose a 16×16 image.
  • Save, publish and close.
  • Repeat steps 2 – 5 for a 32×32 sized image.

With the icons added as web resources we can now associate them with the button using the Image16by16 and Image32by32 parameters.

 

Adding a Command Definition

We now need to define the button’s command which we named earlier as “Cmd_OpenNewDialog”. In the command definition we can set up the action which will occur when the button is pressed.

<CommandDefinitions>

        <CommandDefinition Id=”Cmd_OpenNewDialog”>

               <EnableRules/>

               <DisplayRules/>

               <Actions>

                            <JavaScriptFunction FunctionName=”launchDialog”

                       Library=”$webresource:new_launchDialog”>

                               <StringParameter Value=”8FF84B17-A819-4F21-BAD3-1C75D80CED57″ />

                              <StringParameter Value=”account” />

                              <CrmParameter Value=”FirstPrimaryItemId” />

                       </JavaScriptFunction>

               </Actions>

        </CommandDefinition>  

</CommandDefinitions>

 

We need to define the type of action the button will control. Here we have a reference to a custom JavaScript web resource named “new launchDialog”. Pressing the button will call the launchDialog function, passing in the GUID of the Dialog we wish to launch, the entity name and the FirstPrimaryItemId CRM Parameter, which will be the GUID of the currently open Account record.

 

Note: Another possible command action is to open a web page. In that case we’d use the following action:

<Actions>

        <Url Address=”http://www.bridgeall.com” />

</Actions>

 

 

If we want to control when buttons are displayed and enabled we will have to create some rule definitions.

Adding Rule Definitions

Enable rules can be used to define when the button can be clicked and when it is disabled (greyed out). Display rules can be used to define when the button will appear on the form. There are a variety of rules which can be specified for both but for the purposes of this scenario we’ll be using the FormStateRule. For details on the other rules check out the below links: Enable Rules: http://msdn.microsoft.com/en-us/library/gg328073.aspx

Display Rules: http://msdn.microsoft.com/en-us/library/gg334209.aspx

<RuleDefinitions>

   <TabDisplayRules />

   <EnableRules>

               <EnableRule Id=”Mscrm.Isv.account.Form.B_newformbutton.Enable”>

                       <FormStateRule State=”Existing” InvertResult=”false” />

               </EnableRule>

        </EnableRules>

        <DisplayRules>

               <DisplayRule Id=”Mscrm.Isv.account.Form.B_newformbutton.DisplayRule”>

                       <FormStateRule State=”Disabled” InvertResult=”true” />

               </DisplayRule>

        </DisplayRules>

</RuleDefinitions>

 

For the Enable Rule above, the button will be enabled if the form state is “Existing”. This will prevent the button from being clicked on a New Account form.

For the Display Rule above, the button will be shown if the form state is not “Disabled”. This will prevent the button from being visible for deactivated records.

Finally, we can associate the Cmd_OpenNewDialog command with our new enable and display rules.

<CommandDefinitions>

        <CommandDefinition Id=”Cmd_OpenNewDialog”>

               <EnableRules>

                       <EnableRule Id=”Mscrm.Isv.account.Form.B_newformbutton.Enable”/>

               </EnableRules>

               <DisplayRules>

                       <DisplayRule Id=”Mscrm.Isv.account.Form.B_newformbutton.DisplayRule”/>

               </DisplayRules>

               <Actions>

<JavaScriptFunction FunctionName=”launchDialog” Library=”$webresource:new_launchDialog”>

                              <StringParameter Value=”8FF84B17-A819-4F21-BAD3-1C75D80CED57″ />

                              <StringParameter Value=”account” />

                              <CrmParameter Value=”FirstPrimaryItemId” />

                       </JavaScriptFunction>

               </Actions>

        </CommandDefinition>  

</CommandDefinitions>

 

With the rules added to the command definition, the complete <RibbonDiffXml> should now look as below:

 

<RibbonDiffXml>

   <CustomActions>

            <CustomAction Id=”CI_formlevelOpenDialog”  

            Location=”Mscrm.Form.account.MainTab.Actions.Controls._children”

           Sequence=”151″>

                       <CommandUIDefinition>

                           <Button Id=”B_newformbutton” Command=”Cmd_OpenNewDialog” 

                           LabelText=”Open Dialog”

                           ToolTipTitle=”Open New Dialog” ToolTipDescription=”Open a new Dialog from this custom ribbon button”

                          TemplateAlias=”o1″ Image16by16=”$webresource:new_buttonimage16x16″

                          Image32by32=”$webresource:new_buttonimage32x32″ />

                  </CommandUIDefinition>

               </CustomAction>       

        </CustomActions>

   <Templates>

       <RibbonTemplates Id=”Mscrm.Templates”></RibbonTemplates>

   </Templates>

   <CommandDefinitions>

               <CommandDefinition Id=”Cmd_OpenNewDialog”>

                       <EnableRules>

                              <EnableRule Id=”Mscrm.Isv.account.Form.B_newformbutton.Enable”/>

                       </EnableRules>

                       <DisplayRules>

<DisplayRule Id=”Mscrm.Isv.account.Form.B_newformbutton.DisplayRule”/>

                       </DisplayRules>

                       <Actions>

                                 <JavaScriptFunction FunctionName=”launchDialog”

                               Library=”$webresource:new_launchDialog”>

                                             <StringParameter

                                             Value=”8FF84B17-A819-4F21-BAD3-1C75D80CED57″ />

                                             <StringParameter Value=”account” />

                                            <CrmParameter Value=”FirstPrimaryItemId” />

                                            </JavaScriptFunction>

                       </Actions>

               </CommandDefinition>  

        </CommandDefinitions>

   <RuleDefinitions>

       <TabDisplayRules />

               <DisplayRules>

               <DisplayRule Id=”Mscrm.Isv.account.Form.B_newformbutton.DisplayRule”>

                       <FormStateRule State=”Disabled” InvertResult=”true” />

               </DisplayRule>

               </DisplayRules>

       <EnableRules>

                       <EnableRule Id=”Mscrm.Isv.account.Form.B_newformbutton.Enable”>

                              <FormStateRule State=”Existing” InvertResult=”false” />

                       </EnableRule>

               </EnableRules>

   </RuleDefinitions>

   <LocLabels />

</RibbonDiffXml>

 

 

Importing the solution

After all the changes have been made to the XML document we need to perform the following steps.

  • Save customizations.xml.
  • Zip up the solution folder.
  • Import the solution into CRM.
  • Publish all customizations.

 

Paul 2

 

Button added. Mission Complete.

 

 

Paul 4 Paul 3

 

 

 

Share on FacebookShare on LinkedInTweet about this on TwitterEmail this to someonePin on PinterestPrint this pageShare on Google+Share on Reddit

Tags: , ,


One thought on “CRM – adding a custom button to the form ribbon

Leave a Reply

Your email address will not be published. Required fields are marked *