Let’s start by framing an example. On the Phone Call form we have Ribbon buttons for both “Convert to Case” and “Convert to Opportunity”:
You’ll note the poor Convert to Case button got the short straw and is presented as a small button, whilst the Convert to Opportunity button appears in full and with a text label. But what if we are implementing CRM for Customer Service? In that scenario we are unlikely to care about Opportunities and would likely prefer these buttons switched around. Here’s how we do that…
As described in my previous posts customising the ribbon involves a bit of initial research and then some manual editing of an exported customization XML file. For the research component what we need to do is have a look at the ribbon definition for the Phone Call form. We find that in the SDK here:
[UPDATE: 14 Dec 2011 – The latest SDK did not include the ribbon definition XML files forcing you to build and run an app from source code provided in order to generate them for your self. I provide instructions on this process here]
Open that file in Visual Studio and locate the XML that represents these buttons we want to change. In this case we want to find the form ribbon’s Main tab:
Always make sure you are looking at the right Tab as similarly named button may appear on the SubGrid tab and HomepageGrid tabs as well.
The lesson for first timers I want to reiterate here is DO NOT change this XML file. It will have no effect. This file is essentially documentation of the out-of-the-box CRM ribbons it is no way used by CRM to render the ribbons. To change the ribbon we need to make entries into an exported customization.xml file that contains the definition of the Entity involved.
So jump back to CRM, create a Solution called PhoneCall and add the Phone Call entity into that Solution. Export that Solution, unzip the file and then open customization.xml file in Visual Studio. Collapse the EntityInfo and FormXml nodes and you should see the RibbonDiffXml node, this is where we specify changes to the Ribbon:
Replace the CustomActions line with the following XML:
<CustomActions> <CustomAction Id="GT.switch.button.sequence1" Location="Mscrm.Form.phonecall.MainTab.Convert.Controls._children" Sequence="1"> <CommandUIDefinition> <Button Id="Mscrm.Form.phonecall.Convert.Opportunity" Command="Mscrm.Form.ConvertToOpportunity" Sequence="21" Alt="$Resources:MenuItem_ToolTip_ConvertToOpportunity" LabelText="$Resources:MenuItem_Label_ConvertToOpportunity" Image16by16="/_imgs/ribbon/ConvertOpportunity_16.png" Image32by32="/_imgs/ribbon/ConvertOpportunity_32.png" ToolTipTitle="$Resources:Mscrm_Form_Other_MainTab_Actions_Convert_Opportunity_ToolTipTitle" ToolTipDescription="$Resources:Mscrm_Form_Other_MainTab_Actions_Convert_Opportunity_ToolTipDescription" TemplateAlias="o2" /> </CommandUIDefinition> </CustomAction> <CustomAction Id="GT.switch.button.sequence2" Location="Mscrm.Form.phonecall.MainTab.Convert.Controls._children" Sequence="2"> <CommandUIDefinition> <Button Id="Mscrm.Form.phonecall.Convert.Case" Command="Mscrm.Form.ConvertToCase" Sequence="9" Alt="$Resources:MenuItem_ToolTip_ConvertToCase" LabelText="$Resources:MenuItem_Label_ConvertToCase" Image16by16="/_imgs/ribbon/ConvertCase_16.png" Image32by32="/_imgs/ribbon/ConvertCase_32.png" ToolTipTitle="$Resources:Mscrm_Form_Other_MainTab_Actions_Convert_Case_ToolTipTitle" ToolTipDescription="$Resources:Mscrm_Form_Other_MainTab_Actions_Convert_Case_ToolTipDescription" TemplateAlias="o1" /> </CommandUIDefinition> </CustomAction> </CustomActions>
Here’s a breakdown of the XML…
This first bit:
Reads as: “I want to perform a Custom Action, lets call my action GT.switch.button.sequence1. I want to change one of the child nodes in the ribbon definition under the node that has the Id: “Mscrm.Form.phonecall.MainTab.Convert.Controls”.
Then we have:
Here we are defining a button. Now what I did here was I copy and pasted the definition of the Convert to Opportunity button from phonecallribbon.xml into this customization.xml file. I then changed the properties that I wanted changed. Specifically I changed the Sequence so that this button would be rendered after the Convert to Case button (which has Sequence 20) and I changed the TemplateAlias to o2 so that this button will be rendered as a little button. I think this is important as this button group has been defined as 1 big + 2 small button group and I don’t want to defy that. Those are the only 2 items I have changed. Because the Id I have specified for this button matches an existing button CRM knows to merge my definition with its existing definition and overwrite it’s definition with mine, rather than creating a new button.
In my XML snippet in addition to the above I have a second Custom Action containing a second button definition where I specify the overrides I want to the Convert to Case button. Each button definition needs to sit under it’s own Custom Action header, hence this structure.
That’s it. To deploy we simply zip back up the customization.xml file along with it’s other solution files and then import that solution zip file back into CRM and Publish.
Here’s the end result:
You can follow this same approach to change buttons icons, button labels, etc.
Note: to retain both buttons as large buttons simply set TemplateAlias="o1" on each: