Understanding CRM Ribbon XML - Part 2: updating the ribbon

This is part 2 in a series of posts about the CRM 2011 Ribbon:

• Part 1 - Content and Structure of the Ribbon.
• Part 2 - Editing the ribbon (this post)
• Part 3 - How Ribbon Templates work (coming soon)

How to edit a ribbon

You edit a ribbon by updating the RibbonDiffXml section of the Customizations.xml file. This file is part of the CRM solution zip file that is exported from CRM. Basically, you must create a new solution in CRM that contains the entity who’s ribbon you want to edit. Then you must export the solution and extract the customizations xml file from the exported zip file. See this page for more information on how to export and import ribbons.

Now remember, the CRM solution only contains the changes to the ribbon, so when you view the RibbonDiffXml for a solution exported from CRM, you will not see the full definition of the ribbon. In fact, if no changes to the ribbon have been made yet, it will be almost empty:

One thing that is important to realize is that the different sections of the ribbon are edited differently. To add a new CommandDefinition, EnableRule, or DisplayRule, you can simply insert the new item into the appropriate section inside the RibbonDiffXml:

CustomActions

However, to change anything in the UI section, you need to create CustomActions. Each CustomAction tells CRM to make a change to the UI section of the ribbon. A customAction could tell CRM to insert a new button into the ribbon UI. Or a CustomAction could tell CRM to remove an existing button from the UI. Essentially, each CustomAction either defines a block of XML that should be inserted into the UI section of the ribbon, or indicates which element of the XML should be removed from the ribbon.

Take a look at this example:

This CustomAction tells CRM to insert the XML inside the CommandUIDefinition element into the XML element defined by the Location attribute (highlighted in yellow). In this case the CustomAction is inserting a new Button element into the Mscrm.HomepageGrid.account.MainTab.Collaborate.Controls element.

Notice that the Location attribute has “_children” at the end of it. This is just a convention used by CRM, it means “insert the xml content into the children of the specified element”.

This is what the base ribbon xml looks like after CRM has used the CustomAction to insert the button into the “Mscrm.HomepageGrid.account.MainTab.Collaborate.Controls” element:

Removing Existing Buttons and Controls

If you want to remove an existing element from a ribbon, you can use HideCustomAction. With HideCustomAction, you just specify which element inside the ribbon UI to hide. For example, the following will hide the ExportData button on the account homepage ribbon:

<HideCustomAction Location="Mscrm.HomepageGrid.quote.MainTab.ExportData"

HideActionId="Sample.HomepageGrid.quote.MainTab.ExportData.HideAction" />

Remember, each solution only defines the actions used to change the base ribbon xml. So you could have one CRM solution that adds a ribbon button, and then another Solution layered on top of it that hides the same button.

A quick note about LocLabels

In the RibbonDiffXml from your solution, you will see a RibbonDiffXml section that doesn’t appear in the Base ribbon XML from the resources\exportedribbonxml. This is where you store the localized labels, tooltips, and descriptions for your custom ribbon buttons. Labels are defined in the LocLabels section of the RibbonDiffXml and are referenced by the controls using the “$LocLabels:” syntax:

<Button Id="Sample.account.grid.SendToOtherSystem.Button"

Command="Sample.account.grid.SendToOtherSystem.Command"

LabelText="$LocLabels:Sample.account.SendToOtherSystem.LabelText"

TemplateAlias="o1"

Image32by32="$webresource:sample_/icons/TIcon32x32.png" />

Why don’t LocLabels appear in the base ribbon xml? I suspect it’s because none of the built-in CRM buttons actually use LocLabels, instead they use their own localized resources embedded in the CRM application.

To recap:

1. The ribbon XML definition cannot be edited directly, instead you must edit the RibbonDiffXml from the solution customizations.xml file.
   
2. New CommandDefinitions, EnableRules, and DisplayRules can be added directly to the available sections in the RibbonDiffXml.
   
3. New UI elements (i.e, new buttons, groups, or tabs) must be added to the ribbon using CustomActions
   
4. Existing tabs, groups, and buttons can be hidden using HideCustomActions.

In the next post I will discuss how the CRM Ribbon uses Templates to determine positioning and size of ribbon controls.