Adding a new Button Group to the CRM Ribbon
Here’s a quick run through on how to add a new Group of buttons to the ribbon in Microsoft CRM 2011.
Here’s the end result that will be achieved:
In this scenario we are customising the Phone Call entity’s Form ribbon. In particular the Main Tab of that ribbon (the tab that carries the name of the Entity).
To implement this change we need to customise the Phone Call entity. At present CRM does not provide a UI for Ribbon customisations but the customisation XML does support these changes. So we need the Phone Call entity’s customization xml. Create a Solution, add the Phone Call entity, export the solution, unzip and then open the 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="Mscrm.Form.phonecall.CustomGroup.CustomAction" Location="Mscrm.Form.phonecall.MainTab.Groups._children" Sequence="110"> <CommandUIDefinition> <Group Id="Mscrm.Form.phonecall.CustomGroup.Group" Command="Mscrm.Form.phonecall.CustomGroup.Command" Title="Gareths Group" Sequence="51" Template="Mscrm.Templates.Flexible2"> <Controls Id="Mscrm.Form.phonecall.CustomGroup.Controls"> <Button Id="Mscrm.Form.phonecall.CustomGroup.Button.A" Command="Mscrm.Form.phonecall.CustomGroup.Button.A.Command" Sequence="10" LabelText="Button 1" ToolTipTitle="TipTitle" ToolTipDescription="TipDescription" TemplateAlias="o1" Image16by16="/_imgs/ribbon/newchart16.png" Image32by32="/_imgs/ribbon/newchart32.png" /> <Button Id="Mscrm.Form.phonecall.CustomGroup.Button.B" Command="Mscrm.Form.phonecall.CustomGroup.Button.B.Command" Sequence="20" LabelText="Button 2" ToolTipTitle="TipTitle" ToolTipDescription="TipDescription" TemplateAlias="o1" Image16by16="/_imgs/ribbon/CustomEntity_16.png" Image32by32="/_imgs/ribbon/CustomEntity_32.png" /> </Controls> </Group> </CommandUIDefinition> </CustomAction> <CustomAction Id="Mscrm.Form.phonecall.CustomGroup.MaxSize.CustomAction" Location="Mscrm.Form.phonecall.MainTab.Scaling._children" Sequence="120"> <CommandUIDefinition> <MaxSize Id="Mscrm.Form.phonecall.CustomGroup.MaxSize" GroupId="Mscrm.Form.phonecall.CustomGroup.Group" Sequence="21" Size="LargeLarge" /> </CommandUIDefinition> </CustomAction> <CustomAction Id="Mscrm.Form.phonecall.CustomGroup.Popup.CustomAction" Location="Mscrm.Form.phonecall.MainTab.Scaling._children" Sequence="140"> <CommandUIDefinition> <Scale Id="Mscrm.Form.phonecall.CustomGroup.Popup.1" GroupId="Mscrm.Form.phonecall.CustomGroup.Group" Sequence="85" Size="Popup" /> </CommandUIDefinition> </CustomAction> </CustomActions>
We are adding 3 Custom Actions here:
- The first Custom Action adds the new Group and the 2 Buttons inside that Group.
- The second Custom Action adds the MaxSize definition for the Group to the Scaling definition of the Ribbon. This tells CRM how to display the buttons when the screen size does not require any collapsing of the buttons.
- The third Custom Action adds the Scale definition for the Group to the Scaling definition of the Ribbon. This tells CRM how to display the buttons when the screen size is insufficient.
To adjust my sample code for your scenario do the following:
Do a Find and Replace on “phonecall”, replacing with the name of your entity.
Change the Location value on line 3 to the relevant Group ID of your entity’s Ribbon definition. I’ll explain. In my scenario I wanted to add a Button Group to the Phone Call form’s Main tab so I went and found the Phone Call ribbon definition 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]
And looked for my Tab in that file, finding it here (see the yellow highlight below):
I wanted to add a new Group under the Groups section of the Ribbon so the Location value in our customization file needs to be that Groups Id (highlighted in green above) – appended with ._children. i.e.:
That’s all you need to change at this stage. We’ll come back and personalise other settings in a sec, let’s just try and get the button group to appear first.
Ok, now we need to add some commands to our customization file. Replace the CommandDefinitions line with the following XML:
<CommandDefinitions> <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Button.A.Command"> <EnableRules /> <DisplayRules /> <Actions> <Url Address="http://www.google.com" /> </Actions> </CommandDefinition> <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Button.B.Command"> <EnableRules /> <DisplayRules /> <Actions> <Url Address="http://www.google.com" /> </Actions> </CommandDefinition> <CommandDefinition Id="Mscrm.Form.phonecall.CustomGroup.Command"> <EnableRules> <EnableRule Id="Mscrm.ConvertActivity" /> </EnableRules> <DisplayRules> <DisplayRule Id="Mscrm.ConvertActivity" /> </DisplayRules> <Actions /> </CommandDefinition> </CommandDefinitions>
Here again we have 3 bits, 3 Command Definition’s:
- The first Command Definition defines what should happen when the first button is clicked. I just have a hardcoded URL being launched.
- The second Command Definition defines the 2nd button’s action.
- And the third Command Definition defines when the Group of buttons should be enabled and visible. You can alternatively set these rules per button. You’ll see I am referring to a rule called “Mscrm.ConvertActivity”. I got this from the phonecallribbon.xml. This is the rule used for the Convert to Case button. I find it’s handy to just steal the rule of another button who’s behaviour you want to mimic.
To adjust my sample code for your scenario do the following:
Change the URL being launched by each button or replace s jscript function call like the below:
And find a Display Rule and Enable Rule in your entity’s ribbon.xml that you can use. You can’t just use my “Mscrm.ConvertActivity” rule as it may not exist on your entity.
Ok, that should be enough to get our buttons to appear. To deploy, 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. Pop your form and you should now see the new Button group and it’s 2 buttons:
To adjust the appearance you can now go back and tweak some of the XML attributes (after which you would re-zip, import and publish).
To change where the Group appears on the Ribbon change the Sequence value under the Group node:
Refer back to the entity’s ribbon.xml to see what sequence each existing Group has to figure out what value you need to slot your in between:
Change the Button Group label and the label of the individual buttons here:
Change the Button icon here:
You have 2 approaches for setting the button icons. You can browse the entity’s ribbon.xml (or any entity’s ribbon.xml for that matter, or even applicationribbon.xml) and steal the path and filename of a button you want to use. Or, you can upload your own button icons as web resources and then reference the web resource, which is done in this manner:
That should be enough to get you going. Hope this helps someone.