3 - The Anatomy of Ribbon Customisation

In order to understand which customisations you need to apply, you must first understand how Dynamics CRM constructs each ribbon at run-time.

Each ribbon is built using a layering approach with the application ribbon being added to by entity specific ribbons. At each of these layers, ribbon customisations can be applied to change the out-of-the-box functionality. Managed solution customisations can then be added to by unmanaged customisations to form the final ribbon that is displayed to the user.

The Application Ribbon Tabs are a special group of tabs that are applied throughout the system. They fall into two categories:

  1. Entity Tabs  - Ribbon Tabs that are used as the 'template' for entity Home Page, Sub Grid and Form Ribbons
  2. Single Purpose Application Tabs  - Ribbon Tabs that have a single purpose such as the Dashboard ribbon. Each of these tabs usually has a display rule that uses the current page as a way of determining if it should be displayed or not.

The Entity Ribbon Tabs are defined on a per-entity basis and are based upon the Core Application Tabs for entities. Some entities have buttons and commands that are specific to that particular ribbon (e.g. the Qualify Lead button on the Lead) that are only defined in the Entity Ribbon tabs and not in the Application Ribbon Tabs.

Managed or Un-Managed customisations can be applied at either the Application or Entity level, so that they are merged together at run time. For example, a Managed Customisation applied at the Core Application Tab could be changed by a un-Managed customisation at the Entity Ribbon level.

Let's see this in action

To see this merging of customisations in action, we are going to add a customisation to the Application Entity Form Tab, and also to the Contact Entity Form Tab. This will then result in a merged set of buttons.

  1. Create a solution containing the Contact Entity and the Application Ribbon (Client Extensions). Chapter 1 shows you how to do this.
  2. Open up the Ribbon Workbench and select the Application Ribbon, then the Form Ribbon, then the  {!EntityDisplayName} Tab.
  3. Drag a new button onto the tab.

  4. Select the Contact entity, then the Form Ribbon, then the Contact Tab
  5. Drag a new button onto the tab

  6. Publish the solution and then open up a contact in Dynamics CRM -  you will see two buttons - the result of merging the application ribbon with the entity form ribbon.

  7. You can change the order that they are displayed by adjusting the 'Sequence' attribute on the Application Ribbon to be a higher number than the Contact Form button in the Properties Panel
  8. When published, you'll see the Application Ribbon button will appear after the Contact Form since the order of the buttons is determined by the sequence property.

This is where it starts to get interesting. If you re-open your solution and select the Contact Form Ribbon, you'll see that the Application Ribbon button you defined is shown on the ribbon but without it's correct label and without the red tick:

The reason for this is that when the Ribbon Workbench loads the Core Ribbon Definitions for the Contact entity, the Application Ribbon is pre-merged, meaning that the button we added to the Application Ribbon looks as though it is now part of the 'out of the box' ribbon buttons. If you remember from above, the ribbons are built up in layers, and we can add or change the functionality at each of these layers - so we can if we need to change the functionality of the core buttons by 'customising' it at the Contact Ribbon layer:

  1. From within the Contact Form ribbon, select the 'ApplicationRibbon.Button1', click right button and select 'Customise'. This will now place a customised copy of the core button in the Contact Entity Ribbon customisations.
  2. Change the Label and command, and then publish.
  3. When you load up the Contact Form again, you'll see that you've changed the functionality of the Contact entity version of the application ribbon, but if you open up the Account form, you'll see the button is still the base definition.

This kind of layering customisations is very powerful when trying to minimize the number of customisations you need to add to achieve you desired functionality. For example, if you had a particular command that was the same on all entities apart from on the contact ribbon, there was an additional enabled rule, you could add it to the Application Ribbon and then simply customise it on the Contact ribbon as we've just done.

The same approach applies when customising managed solution ribbon extensions - if you load a ribbon that has managed customisations, they will also look like they are part of the out of the box definitions, and allow you to customise them in a layered approach.

Feedback and Knowledge Base