Customize Sub-grid Ribbon Button for Specify Entity in Dynamic CRM 2011

Vincent Zhong, 04 February 2012

Last week I have spent most of my time in customizing Ribbon in Dynamics CRM 2011. There are two types of Ribbon customizations, those working with system ribbon controls and those creating new custom ribbon controls. The basic for these two types of customizations are pretty much the same, and there are already many good tutorials on the Internet showing you how to do it, but I do come across a specific problem which took me many hours to before I figure how to do it. I would like to share this with you.

Here is the scenario. If you open an Account record, click “Orders” on the left navigation, your ribbon area should looks similar to the following screenshot except I have added a new ribbon button called “Test Title”:

Even though you get this ribbon from an Account record, but it actually belongs to the Entity you just clicked on the left navigation, which is “Order” entity. This ribbon is called Subgrid Ribbon, which only appears when the entity is being displayed in a subgrid of another entity. This is the first lesson I learned when I first started working with ribbon in Dynamics CRM 2011.

So I have customized the ribbon for Order entity, and added the custom button like this:

<CustomAction Id="Order.HideButton.CustomAction"
             Location="Mscrm.SubGrid.salesorder.MainTab.Management.Controls._children"
              Sequence="10">
  <CommandUIDefinition> 
    <Button Id="Order.HideButton.Button" Command="Order.HideButton.CommandDefinition"
            LabelText="Test Title" ToolTipTitle="Test Title"
            ToolTipDescription="Test Title" TemplateAlias="o1"
            Image16by16="$webresource:new_/img/clone_icon_32x32"
            Image32by32="$webresource:new_/img/clone_icon_32x32" />
  </CommandUIDefinition>
</CustomAction>

And you need to specify the “<Command>” you used in the “<CommandDefinitions>”, as this ribbon button just for testing purpose only, the Command I created won’t do anything:

<CommandDefinitions> 
  <CommandDefinition Id="Order.HideButton.CommandDefinition">
    <EnableRules /> 
    <DisplayRules /> 
    <Actions /> 
  </CommandDefinition>
</CommandDefinitions>

Now you should see the test button appear when you click the “Orders” on left navigation. But the problem is, as the button is added into the Subrid ribbon of Order entity, it will show on the subgrid ribbon for all entity that has relationship with Order, not only Account. For example when you open an Opportunity record, then click “Orders” on the left navigation, you will also see the “Test” button. That is now what I want.

After many hours of research, I found the solution, which is <FormEntityContextRule>

Change the <DisplayRules /> in <RuleDefinitions> to
<DisplayRules> 
  <DisplayRule Id="Order.HideButton.DisplayIfAccount.DisplayRule">
    <FormEntityContextRule EntityName="account/>"
  </DisplayRule >
</DisplayRules >

Then change the <DisplayRules/> in <CommandDefinition> to
<DisplayRules> 
  <DisplayRule Id="Order.HideButton.DisplayIfAccount.DisplayRule" />
</DisplayRules> 

The code means when the primary entity is Account, this displayrule will return true, therefore the button will be shown. That’s exactly what we need, we need the button to show only for Account entity, not for any other entity.