Pass Microsoft Dynamics 365 data from a page as a parameter to Ribbon Actions

  • Article

 

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

When you define an action in a ribbon, you frequently have to pass data from the page to either a JavaScript function or a URL. This topic describes options for using the <CrmParameter> (RibbonDiffXml) element to retrieve these values.

Grid values

The majority of the values available for the <CrmParameter> (RibbonDiffXml) element are related to working with data displayed in a grid or hierarchy chart. By using the Value attribute enumeration options, you can easily isolate items by:

  • Selected items

    • SelectedControlSelectedItemCount

    • SelectedControlSelectedItemIds

    • SelectedControlSelectedItemReferences

  • All items

    • SelectedControlAllItemCount

    • SelectedControlAllItemIds

    • SelectedControlAllItemReferences

  • Unselected items

    • SelectedControlUnselectedItemCount

    • SelectedControlUnselectedItemIds

    • SelectedControlUnselectedItemReferences

For each of these groupings, you can gather the number of items and the GUID identifier. If you are passing the values to a URL, you can also retrieve EntityReference objects that contain all the information that you need to uniquely identify the objects in the grid. These parameters apply whether the page viewed is the main grid (HomepageGrid) or a sub grid located in a form. When used together with the SelectedEntityTypeName parameter, you have all the information that you must have to pass to another application.

Form values

With a form ribbon, you can use the Xrm.Page.data.entity.attributes collection and the Xrm.Page.ui.controls collection to retrieve values for known fields. However, if you want to pass the value of a selected form field, you’ll have to do more scripting to get the value.

You can use the PrimaryControlId parameter to get the Id value for the control that has focus when the ribbon control received focus. This Id is the Document Object Model (DOM) Id value. To get the data value, you will have to try using that value by using code such as that in the following example:

var focusFieldValue = Xrm.Page.ui.controls.get(PrimaryControlId).getAttribute().getValue()

Context information

In addition to data values, you can retrieve additional context information by using <CrmParameter> (RibbonDiffXml).

For convenience, the Value attribute options OrgName, OrgLcid, and UserLcid are available without requiring that you use Xrm.Page.context to use the getOrgUniqueName, getOrgLcid, and getUserId methods. For a <Url> (RibbonDiffXml) action, you can also use the PassParams attribute to include contextual information.

Value options PrimaryEntityTypeName and FirstPrimaryItemId provide information for an entity record. You can use PrimaryItemIds for a HomepageGrid ribbon to get a list of all the displayed items.

Finally, you can use the CommandProperties value to pass details about the event from the ribbon control. You can use this to send contextual information to a central function where specific actions can be determined based on the context of the event.

See Also

Customize commands and the ribbon
Pass parameters to a URL by using the ribbon
<CrmParameter> (RibbonDiffXml)
<JavaScriptFunction> (RibbonDiffXml)
<Url> (RibbonDiffXml)
Define ribbon actions
Define custom actions to modify the ribbon

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright