Controlling Ribbon Buttons with Jscript in Dynamics CRM 2011

Slalom Consultant Jayson GoldingerCRM 2011 has been out for some time now and I finally had a project where I had a chance to really dig into the functionality of the ribbon. In reading through the software developers kit (SDK), I quickly realized that the Ribbon Enable Rules are somewhat limited in functionality. However, Microsoft left the door open for us to use jscript where the XML will simply not suffice. The use of jscript (and some FetchXML) gives us quite a bit of flexibility that we need out in the implementation world. Let’s walk through how this works…

For the sake of this blog post, I am going to make the assumption that you have a basic understanding of the RibbonDiffXML. In the CommandDefinition for the button you will see the EnableRules. You can have several rules and if any one of the rules returns False, the button will be disabled. You can get to the CommandDefinition for custom buttons by looking in the customizations.xml or you can find the CommandDefination for standard buttons on standard entities in the SDK. Here is a sample of a button’s CommandDefinition; this one is for the standard “Deactivate” button on the Account Entity pulled from the SDK. The highlighted line of the XML is a custom EnableRule that I created.

<CommandDefinition Id=Mscrm.HomepageGrid.Deactivate>
<EnableRules>
<EnableRule Id=Mscrm.VisualizationPaneNotMaximized />
<EnableRule Id=Mscrm.SelectionCountAtLeastOne />
<EnableRule Id=Mscrm.AccountCustomRule />
</EnableRules>
<DisplayRules>
<DisplayRule Id=Mscrm.CanWriteSelected />
<DisplayRule Id=Mscrm.SelectedEntityHasStatecode />
</DisplayRules>
<Actions>
<JavaScriptFunction FunctionName=Mscrm.GridRibbonActions.deactivateLibrary=/_static/_common/scripts/RibbonActions.js>
<CrmParameter Value=SelectedControl />
<CrmParameter Value=SelectedControlSelectedItemReferences />
<CrmParameter Value=SelectedEntityTypeCode />
</JavaScriptFunction>
</Actions>
</CommandDefinition>

Now we have to define the EnableRule. There are really only three items to define here. Start by finding the EnableRules section of the customizations.xml. First, you will need to reference the ID of the rule from the Button CommandDefinition. Next is the FunctionName which is the function being called in your jscript webresource file. Last is the Library which is the jscript webresource where you create your jscript function. Either create a new Web Resource or you can use an existing Web Resource in CRM for your Function. The Web Resource does not have to be associated with the entity’s Form. Here is a sample of what the EnableRule should look like in the Customizations XML:

<EnableRules>
<EnableRule Id=Mscrm.AccountCustomRule />
<CustomRule FunctionName=Jscript_EnableRule Library=$webresource:TestFile.js>
</CustomRule>
</EnableRule>
</EnableRules>

Once you have the EnableRule complete, you can create any jscript function in your Web Resource to set the rule value. In your script simply return “True” or “False” to enable or disable the button. Here is a sample function that I have used:

function Jscript_EnableRule() {
//TRUE will enable the button
var status = Xrm.Page.getAttribute(statuscode).getValue();
var stage = Xrm.Page.getAttribute(new_stage).getValue();
if (stage == 183550000 && status == 183550000) {
return true;
}
if (stage == 183550001 && status == 183550000) {
return true;
}
if (stage == 183550002 && status == 183550000) {
return true;
}
else {
return false;
}
}

At this point you may be thinking this is all great but what is the practical purpose. Well with jscript it becomes much easier to use and/or manage more complex logic on the EnableRule; as most of us are more comfortable using jscript than trying to navigate the SDK. Evaluating multiple fields at one time is almost impossible to do in just the EnableRule XML. Another advantage of this method is that you are able to do a Fetch to check other values like Security Roles, something not available natively, or checking values on related entities. Something else to note is that this feature will execute anywhere the Ribbon appears, not just on the form (i.e. Homepage and Subgrid). The next time you are trying to manage the Ribbon buttons try giving jscript a chance, I believe you will find it quite useful.

About Jayson Goldinger
Jayson Goldinger is a Slalom Consultant based in Denver, CO and a member of the Slalom National CRM Team. His work revolves around Microsoft Dynamics CRM including configuration, customization, report development and integration. He is also recognized as a Scribe MVP.

2 Responses to Controlling Ribbon Buttons with Jscript in Dynamics CRM 2011

  1. Cory Fellers says:

    Jayson, do you know if there is a way to trigger the functionality of an out of the box Ribbon Button automatically from JavaScript on the form?

  2. Neel says:

    It is working very well, thanks for sharing.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 129 other followers

%d bloggers like this: