Define ribbon enable rules

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

When configuring Ribbon elements you can define specific rules to control when the ribbon elements are enabled. The <EnableRule> (RibbonDiffXml) element is used as follows:

  • Use the /RuleDefinitions/EnableRules/EnableRule element to define rules controlling when the ribbon element should be enabled.

  • Use the /CommandDefinitions/CommandDefinition/EnableRules/EnableRule element to associate specific enable rules to a command definition.

What does enabled mean?

With the command bar, commands that are disabled are hidden. With the ribbon, commands that are disabled are visible but do not respond to events.

Control when ribbon elements are enabled

Enable rules are intended to be re-used. By defining them with rule definitions, you can use the same enable rule for many command definitions. When more than one enable rule is defined for a command definition, all of the enable rules must evaluate as true for the ribbon element to be enabled.

All Enable rules provide an optional attribute to specify whether the default value of the rule is true or false and an optional InvertResult attribute to allow for returning a negative result when the item being tested returns true.

The /RuleDefinitions/EnableRules/EnableRule element supports the following types of rules:

  • <CommandClientTypeRule> (RibbonDiffXml)
    Specifies a rule that detects the type of presentation being used.

    The Type values correspond to the following:

    Value

    Presentation

    Modern

    The command bar is presented using Microsoft Dynamics 365 for tablets.

    Refresh

    The command bar is presented using the updated user interface.

    Legacy

    The ribbon is presented in forms for entities that were not updated or in a list view in Microsoft Dynamics 365 for Outlook.

  • <CrmClientTypeRule> (RibbonDiffXml)
    Allows definition of rules depending on the type of client used. Type options are as follows:

    • Web

    • Outlook

  • <CrmOfflineAccessStateRule> (RibbonDiffXml)
    Use this criteria to enable a ribbon element based on whether Microsoft Dynamics 365 for Microsoft Office Outlook with Offline Access is currently offline.

  • <CrmOutlookClientTypeRule> (RibbonDiffXml)
    Use this rule if you want to only display a button for a specific type of Microsoft Dynamics 365 for Outlook. Type options are as follows:

    • CrmForOutlook

    • CrmForOutlookOfflineAccess

  • <CustomRule> (RibbonDiffXml)
    Use this kind of rule to call a function in a JavaScript Library that returns a Boolean value.

    Note

    Custom rules that do not return a value quickly can affect the performance of the ribbon. If you have to perform logic that might take some time to complete, use the following strategy to make your custom rule asynchronous:

    1. Define a rule that checks for a custom object. You might check for an object such as Window.ContosoCustomObject.RuleIsTrue that you just attach to the Window.

    2. If that object exists, return it.

    3. If that object does not exist, define the object and set the value as false.

    4. Before you return a value, use settimeout to execute an asynchronous callback function to re-set the object. Then return false.

    5. After the callback function has performed the operations that are required to determine the correct result, it sets the value of the object and uses the refreshRibbon method to refresh the ribbon.

    6. When the ribbon is refreshed, it detects the object together with the accurate value set and the rule is evaluated.

  • <EntityRule> (RibbonDiffXml)
    Entity rules allow for evaluation of the current entity. This is useful when you define custom actions that apply to the Entity Template instead of for specific entities. For example, you may want to add a ribbon element to all entities except for several specific entities. It is easier to define the custom action for the Entity Template that applies to all entities and then use an Entity Rule to filter out those that should be excluded.

    The entity rule also includes an optional Context attribute to specify whether the entity is being displayed in the Form or a list (HomePageGrid). The optional AppliesTo attribute can be set to PrimaryEntity or SelectedEntity to distinguish whether the entity is being displayed in a subgrid.

  • <FormStateRule> (RibbonDiffXml)
    Use the FormState rule to determine the current type of form that is displaying a record. State options are as follows:

    • Create

    • Existing

    • ReadOnly

    • Disabled

    • BulkEdit

  • <OrRule> (RibbonDiffXml)
    The OrRule lets you override the default AND comparison for multiple enable rule types. Use the OrRule element to define several possible valid combinations to check.

  • <OutlookItemTrackingRule> (RibbonDiffXml)
    Use the TrackedInCrm attribute for this element to determine whether the record is being tracked in Microsoft Dynamics 365.

  • <OutlookVersionRule> (RibbonDiffXml)
    Use this to enable a ribbon element for a specific version of Microsoft Office Outlook as follows:

    • 2003

    • 2007

    • 2010

  • <PageRule> (RibbonDiffXml)
    This type of rule checks the URL of the page being displayed. It returns true if the Address matches.

  • <RecordPrivilegeRule> (RibbonDiffXml)
    Use this rule to determine whether the current user has privileges on a specific record. These privileges differ from an Entity privilege because they can include privileges gained by another user sharing the record with the current user.

  • <SelectionCountRule> (RibbonDiffXml)
    Use this kind of rule with a ribbon displayed for a list to enable a button when specific maximum and minimum numbers of records in the grid are selected. For example, if your button merges records, you should make sure at least two records are selected before enabling the ribbon control.

  • <SkuRule> (RibbonDiffXml)
    Use this kind of rule to enable a ribbon element for a specific SKU version of Microsoft Dynamics 365 as follows:

    • OnPremise

    • Online

    • Spla

  • <ValueRule> (RibbonDiffXml)
    Use this rule to check the value of a specific field in the record being displayed in the form. You must specify the Field and the Value to check.

See Also

Customize commands and the ribbon
Define ribbon commands
Define ribbon display rules

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright