The Microsoft Dynamics CRM Blog
News and views from the Microsoft Dynamics CRM Team

Create Dynamic Ribbon Controls

Create Dynamic Ribbon Controls

  • Comments 4

Microsoft Dynamics CRM 2011 uses Ribbons (also known as Fluent UI) to provide a user interface to display the right commands at the right time. Ribbons also provide a very powerful and flexible way of extending the ribbon functionality to meet your requirements. If you are new to ribbon customization in Microsoft Dynamics CRM 2011, see the SDK documentation: Customize the Ribbon for Microsoft Dynamics CRM.

I’m going to show you how to create dynamic Ribbon controls. You will typically use dynamic controls so that your ribbon elements can react to changes in data or context. ComboBox, DropDown, FlyoutAnchor, MRUSplitButton and SplitButton controls can contain other collections of controls. These controls can be created with static definitions at design time or they can be populated dynamically using a JavaScriptFunction that uses a Script Web Resource.

In this article I will demonstrate how to dynamically create ribbon Button elements and populate them inside a FlyoutAnchor. The end result will look like this:

image

The procedure uses these steps:

  1. Define the Parent Control
  2. Define CommandDefinitions
  3. Create a Script Web Resource

Define the Parent Control

Once you determine the location where you would like to create a dynamic menu, create a CustomAction to add the CommandUIDefinition as shown below.

<CustomAction Id="Add_Dynamic_Menu" Location="Mscrm.BasicHomeTab.Tools.Controls._children"> <CommandUIDefinition> <FlyoutAnchor Id="ISV.DynamicFlyoutAnchor" Sequence="100" Command="Mscrm.Enabled" Image16by16="/_imgs/placeholders/ribbon_placeholder_16.png" Image32by32="/_imgs/ribbon/newrecord32.png" LabelText="Dynamic Menu" Alt="Dynamic Menu" PopulateDynamically="true" PopulateQueryCommand="ISV.PopulateMenu" TemplateAlias="isv" /> </CommandUIDefinition> </CustomAction>

The value of the CustomAction Location attribute shows that I have chosen to add a FlyoutAnchor to the Tools group of the Basic Home Tab.

Set the value of PopulateDynamically attribute to true. This attribute will tell the rendering engine to populate the content of the menu dynamically. Specify the Id value of the CommandDefinition you will create in the next step to the PopulateQueryCommand attribute. The next step will show how to define the CommandDefinition.

Define CommandDefinitions

There are two CommandDefinition elements:

  • ISV.PopulateMenu: In addition to the “command” property used by standard controls, dynamically populated controls utilize another command “PopulateQueryCommand” which is responsible for retrieving the dynamic data.
    • This CommandDefinition will control what elements will be shown.
    • It uses the Jscript function named "DynamicMenu".
  • ISV.SearchCommand
    • This CommandDefinition will control what actions should be performed when the dynamically generated control elements are clicked.
    • It uses the Jscript function named "Search".

Each CommandDefinition contains a JavaScriptFunction action that specifies the Script Web resource. Specify the unique name of the Script Web resource with $webresource: prefix to the Library attribute.

<CommandDefinition Id="ISV.PopulateMenu"> <EnableRules> <EnableRule Id="Mscrm.Enabled" /> </EnableRules> <DisplayRules /> <Actions> <JavaScriptFunction FunctionName="DynamicMenu" Library="$webresource:new_dynamicmenupopulator.js"> <CrmParameter Value="CommandProperties" /> </JavaScriptFunction> </Actions> </CommandDefinition> <CommandDefinition Id="ISV.SearchCommand"> <EnableRules /> <DisplayRules /> <Actions> <JavaScriptFunction FunctionName="Search" Library="$webresource:new_dynamicmenupopulator.js"> <CrmParameter Value="CommandProperties" /> </JavaScriptFunction> </Actions> </CommandDefinition>

Important:

For both CommandDefinition elements, you must use the CrmParameter with the Value attribute set to "CommandProperties". This object will be used later in the script web resources to read which dynamically generated button is selected and to set the dynamically generated ribbon xml.

Create a Script Web Resource

Create a Script Web resource named new_dynamicmenupopulator.js. Set the contents of this JScript library to the following code:

function DynamicMenu(CommandProperties) { var menuXml = '<Menu Id=\"ISV.DynamicMenu\"><MenuSection Id=\"ISV.Dynamic.MenuSection\" Sequence=\"10\"><Controls Id=\"ISV.Dynamic.Controls\"><Button Id=\"ISV.Dynamic.Button1\" Command=\"ISV.SearchCommand\" Sequence=\"20\" LabelText=\"Test Button1\" Alt=\"Test Button1\" /><Button Id=\"ISV.Dynamic.Button2\" Command=\"ISV.SearchCommand\" Sequence=\"30\" LabelText=\"Test Button2\" Alt=\"Test Button2\" /></Controls></MenuSection></Menu>'; CommandProperties.PopulationXML = menuXml; } function Search(CommandProperties) { var controlId = CommandProperties.SourceControlId; switch (controlId) { case 'ISV.Dynamic.Button1': alert('Button 1 Command Implementation'); break; case 'ISV.Dynamic.Button2': alert('Button 2 Command Implementation'); break; default: alert('Button Unknown'); } }

This library contains two functions:

DynamicMenu Function

The DynamicMenu function defines the XML for a Menu element containing Button definitions. In this example, there are two buttons defined within a MenuSection element. Each Button uses the following attribute values:

  • ISV.Dynamic.Button1
    • Command: ISV.SearchCommand
    • Sequence: 20
    • LabelText: Test Button1
    • Alt: Test Button1
  • ISV.Dynamic.Button2
    • Command: ISV.SearchCommand
    • Sequence: 30
    • LabelText: Test Button2
    • Alt: Test Button2

Both of these buttons are configured to use the ISV.SearchCommand created in the previous step.

Search Function

The Search function is called when buttons are clicked at run time. Because the CommandDefinition you created in the first step passes the value "CommandProperties", this object is passed through and you can read the SourceControlId property to determine which of the dynamically generated buttons was clicked and perform the appropriate action.

Thanks,

Mesganaw Anteneh



  • Usage of FlyoutAnchor is explained very well. This works for web version. But does not work on Outlook version. Is there any way to make it work in Outlook Client ribbon

    CRM Version: 5.0.9688.1045

  • Is it possible to use a similar technique to alter the built-in dynamic ribbon controls?

    My client wants me to Service Activity everywhere, and I can hide it as a related entity, and on the application ribbon, but in the Jewel (File) menu and in the NewActivity Flyout (Mscrm.Jewel.NewMenu.NewActivity) it still shows up.

    I'm thinking that I could create a new PopulateQueryCommand that calls the built in one, (Mscrm.DynamicMenu.NewActivity) then uses a Linq.Exclude to remove the NewServiceActivity option before passing the collection on to the UI.

  • How can we do it if we want to insert a combo/dropdown in Ribbon?

  • Hi there,

    I have implemented a similar functionality and it works ok to an extend, i.e. js script function is called, but the CommandProperties parameter is not passed. Does anyone know what could have gone wrong?

    Thank you in advance

Page 1 of 1 (4 items)
Leave a Comment
  • Please add 8 and 5 and type the answer here:
  • Post