Understanding CRM Ribbon XML - Part 1: ribbon content and structure

This is part 1 in a series of posts about the CRM 2011 Ribbon:
 - Part 1 - Content and Structure of the Ribbon. (this post)
 - Part 2 - Editing the ribbon.
 - Part 3 - How Ribbon Templates work (coming soon)

Demystifying the CRM 2011 ribbon xml

The CRM 2011 SDK provides a number of walkthroughs on adding buttons and tabs to the CRM entity ribbons, but they don’t really offer an in-depth explanation of why each step is necessary, or what other options are available. In the next few posts I will attempt to explain fully how the ribbons for CRM 2011 can be customized, and explain in more detail some of the areas that the SDK only touches lightly. In this first post I will cover the basic structure and content of the ribbon XML, and in following posts we'll go over editing the ribbon and how ribbon templates work. 

Your CRM solution doesn’t contain the entire ribbon

The first thing you must know about CRM ribbons, is that a CRM solution will not contain the entire definition of a ribbon. The CRM database does contain a base ribbon definition for each entity, but this definition is not directly customizable. When you modify the ribbon, your CRM solution will only store the changes made to the ribbon. This way multiple solutions can each make changes to the same ribbon and they will all get layered on top of each other, without any solutions overwriting each other.

So when making changes to any CRM ribbon you have to keep in mind that you’re not actually editing the ribbon XML definition, you are editing an XML file (ribbondiffxml) that describes the changes made to the ribbon.

Viewing the Full Ribbon Definition

Each ribbon in CRM is defined by an xml file, and the first thing you should do when trying to understand how ribbon customization works is to look at the full ribbon xml for a CRM entity. There are two ways you can get the ribbon xml for an entity:

1. Look in the resources\exportedribbonxml folder in the CRM SDK. This folder contains the ribbon xml for all the system entities in CRM.
   
   
2. Or, you can export the ribbon xml for a specific entity programmatically, using the RetrieveEntityRibbonRequest message. For uncustomized system entities this will give you the same xml that is found in resources\exportedribbonxml.

Both of these methods will give you the full ribbon definition from CRM (not just the customizations you’ve added to the ribbon).


Contents of the Ribbon XML

As you look through the ribbon xml you will see four main sections: UI, Templates, CommandDefinitons, and RuleDefinitions.

1. UI – The UI section contains all the Tabs, Groups, and buttons that show up in the ribbon. This defines what you actually see in the ribbon.
   
   
2. Templates – Templates define the layout of ribbon groups. The size of buttons and controls on a ribbon, how they are arranged, and how they collapse when the window size shrinks all depends on what templates the ribbon is using.
   
   
3. CommandDefinitons – CommandDefinitions define what the ribbon buttons do (i.e., what actions are executed when a user clicks the button).
   
   
4. RuleDefinitions – RuleDefinitions define when a button is displayed and when it is enabled or disabled.
   
   

UI Section

Take a look at the xml inside the UI section and you will see a hierarchy of Tabs, which contain Groups, which then contain Controls (including ribbon buttons). Each of these elements corresponds to a part of the ribbon:

For the most part, the UI section is pretty straightforward, but there are a few things worth pointing out:

1. Notice that there are several different types of tabs: HomepageGrid, Form, and SubGrid. These tabs will be difference parts of the CRM application. Read about the different types of tabs here.
   
   
2. Each button has a sequence number and a TemplateAlias. These are used to derermine the ordering of the buttons and the size of the button. We’ll look at how templates work in the next post.
   
   
3. Inside each tab, in addition to a collection of Groups you will see a “Scaling” section. Ignore this section for now, we’ll get to it in a bit (essentially, it defines how the groups behave when there isn’t enough room on the screen to display the full ribbon).
   
   

Command Definitions

Look at the Buttons in the UI section:

Notice that the buttons each have a “Command” attribute. If we search the XML file for the command, we see that it’s a reference to a CommandDefinition (which is found in the commandDefinitions section, of course):

You can see that in the CommandDefinition, there is an Action, and also a number of DisplayRules and EnableRules. The Action defines what happens when the button is pressed. The Action can be either a Javascript function or a URL. In the example shown above, the action calls the “openObj” JavaScript function. See this page for more information on how to define ribbon actions.


RuleDefinitions

The EnableRules and DisplayRules in the CommandDefinition define which rules are used to determine when the button is enabled or visible. The rules you see inside the CommandDefinition are just pointers, the actual definitions of these rules are defined in the RuleDefinitions section:

There are many different kinds of rules that can be used within each EnableRule or DisplayRule, allowing you to create complex conditions for almost any kind of scenario. In the example shown above, the CreateSelectedEntityPermission rule uses an EntityPrivilegeRule to make sure that the “New Record” button is only enabled when the current user has the Create permission on the selected entity. To understand the full capability of EnableRules and DisplayRules, check out the following SDK articles: EnableRules, DisplayRules.

In Conclusion..

To recap, we have the UI section, which defines the actual visual elements that make up a ribbon. The buttons in the UI section link to a CommandDefinition, which defines what the button does. And the CommandDefinition links to multiple RuleDefinitions, which define when the button is visible or enabled. What about the Templates section? We will get to that in a future post.

In the next post, we'll see how to actually edit the ribbon.