Execution context (client-side reference)

 

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

The execution context is an optional parameter that can be passed to a JavaScript library function through an event handler. This option is presented in the handler properties dialog when you specify the name of the function. This option is set for a <Handler> (FormXml) element using the passExecutionContext attribute.

Execution context is automatically passed to functions set using the Xrm.Page.data.addOnSave and Xrm.Page.data.entity Attribute.addOnChange, and Xrm.Page.ui Control.addPreSearch methods.

Execution context methods

  • getContext
    Method that returns the Client-side context (client-side reference) object.

  • getDepth
    Method that returns a value that indicates the order in which this handler is executed.

  • getEventArgs
    Method that returns an object with methods to manage the Save event.

  • getEventSource
    Method that returns a reference to the object that the event occurred on.

  • getFormContext
    Method that returns reference to either a form or editable grid depending on where the method was called.

  • Shared variables
    Shared variables allow sharing of a variable with other handlers for the same event. You use the setSharedVariable and getSharedVariable methods to work with shared variables.

getContext

Method that returns the Client-side context (client-side reference) object

ExecutionContextObj.getContext()
  • Return Value
    Type: Object

getDepth

Method that returns a value that indicates the order in which this handler is executed.

  • Return Value
    Type: Number

    The order begins with 0.

getEventArgs

Method that returns an object with methods to manage the Save event.

Note

This method returns null for any event other than the Save event.

ExecutionContextObj.getEventArgs()

getEventSource

Method that returns a reference to the object that the event occurred on.

ExecutionContextObj.getEventSource()
  • Return Value
    Type: Object

    This method returns the object from the Xrm.Page object model that is the source of the event, not an HTML DOM object. For example, in an OnChange event, this method returns the Xrm.Page.data.entity attribute object that represents the changed attribute.

getFormContext

Method that returns a reference to either the form (Xrm.Page) or editable grid depending on where the method was called.

ExecutionContextObj.getFormContext()
  • Return Value
    Type: Object

    This method returns a reference either to the object from Xrm.Page object model or to the GridRow object in an editable grid depending on where the method was called. This method enables you to create common event handlers that can operate either on a form or editable grid depending on where its called.

    More information: Use the Xrm.Page object model and Editable grid objects and methods (client-side reference)

    Note

    This method was introduced in December 2016 update for Dynamics 365 (online and on-premises).

  • Example
    The following sample code demonstrates how you can create a method that sets notification on a form field or editable grid cell depending on where you registered the script (Field OnChange event or editable grid OnChange event):

    function commonEventHandler(executionContext) {
        var entityObject = executionContext.getFormContext().data.entity;
        var telephoneAttr = entityObject.attributes.getByName('telephone1');
        var isNumberWithCountryCode = telephoneAttr.getValue().substring(0,1) === '+';
    
        // telephoneField will be an Xrm.Page control if invoked from a form OnChange event;
        // telephoneField will be a editable grid GridCell object if invoked from editable grid OnChange event.
        var telephoneField = telephoneAttr.controls.getByIndex(0);
    
        if (!isNumberWithCountryCode) {
            telephoneField.setNotification('Please include the country code beginning with ‘+’.', 'countryCodeNotification');
        }
        else {
            telephoneField.clearNotification('countryCodeNotification');
        }
    }
    

Shared variables

Shared variables allow sharing of a variable with other handlers for the same event. You use the setSharedVariable and getSharedVariable methods to pass variables between functions.

setSharedVariable

Sets the value of a variable to be used by a handler after the current handler completes.

ExecutionContextObj.setSharedVariable(key, value)
  • Arguments
    String: The name of the variable

    Object: The value to set.

getSharedVariable

Retrieves a variable set using setSharedVariable.

ExecutionContextObj.getSharedVariable(key)
  • Arguments
    String: The name of the variable.

  • Return Value
    Type: Object

    The specific type depends on what the value object is.

See Also

Client-side programming reference

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright