Hardcore CRM: Dynamic provisioning – structure of the ribbon

In my last article, I managed to export and import the ribbon dynamically. At this point I need to alter the contents of the particular ribbon. The way I want to alter the ribbon, is by simply injecting XML strings into the ribbon, or by simply removing XML strings from the ribbon.

This task is not really hard if you know the structure of the ribbon. In this article I’ll give an explanation of the ribbon. Prepare yourself for some XML to come.

The XML needed to provision the ribbon is embedded in within the XML needed to provision the ribbon, and can be found in the customizations.xml file within the solution. At a high level the structure of the XML looks like this:

<Entities>
<Entity>
…
<RibbonDiffXml>
<CustomActions />
<Templates />
<CommandDefinitions />
<RuleDefinitions />
<LocLabels />
</RibbonDiffXml>
</Entity>
…
</Entities>

Within the Entity section, you can find the RibbonDiffXml. The RibbonDiffXml describes the additions to the standard system ribbon for the specific entity.

The RibbonDiffXml section is build up in a straight forward manner:

• CustomActions
  In the custom actions you describe the buttons you want to display. Per button you specify what images to show, what labels and titles to display and the location of the button.In the image below, a custom action is described. Pay attention to the sequence values. The sequence value determines the location of the button. The sequence in both the CustomAction and Button should be the same value.

• Templates
  In the templates section, the template is specified that is used to display the ribbon. I don’t tamper with this setting.
• CommandDefinitions
  The command definitions section is the center of the action. In this section, the commands are described that are attached to the buttons.
  Per command definition you describe what action should be performed. In our case the action that should be performed is calling a javascript function.Furthermore we can specify when the button should be enabled or disabled and when it should be visible or hidden. In the image below a command definition is described.The Id of the command definition has to match the command specified in the CommandUIDefintion above. Otherwise nothing will happen when you press the button.In the Actions section, a Javascript function is specified. This javascript function is contained in a javascript file that is stored in the webresources of the solution.

  In the example below, the Id of the current entity is passed in as parameter. The cryptic syntax in the Library: “$webresource:“ specifies that the library can be found in the webresources. CRM will handle the URL resolving.

• RuleDefinitions
  The rule definitions section describe the rules attached to the buttons. There are three sets of rules: Tab rules (ignored for now), Display rules and enable rules.

  In the image below a display rule is described. The Id of the display rule has to match the DisplayRule Id specified in the DisplayRule specified above.
  In this case the button will be visible in case the statuscode of the entity has the value “1234” or “5678”. Otherwise the button is hidden.

• LocLabels
  This section is used when developing multilingual solutions. All text elements like titles and descriptions can be attached to one or more languages codes (1033 = us-en, 1043 = nl-nl, …).In the image below a Localization label is described. The Id of the Localization label has to match the “$LocLabels:…” tag specified in the button definition. The “$LocLabels:“ tag takes care of the translation.As you can see in the example below, two language labels are specified for this localization label.

By injecting these XML fragments in the exported ribbon definition, we can dynamically add buttons to the ribbon. The cool thing is that we can use the Id’s of the various elements to identify if there has been a ribbon modification before. In case there used to be one, we can skip the operation, or we can remove the modification (in case of disabling our functionality).

Anyway enough food for thought.

In the next article, I’ll return to the Document Integration series and finish the tinkering with the ribbon. From there on we can move forward, and build our upload and display functionality.