How to Pass Execution Context to a Web Resource in Dynamics 365

Erick McCollum | 07 May 2020

DISCLAIMER: The opinions expressed on this website are solely my own, and they are not associated with my employer, another person, or another organization in any way. All information on this website is provided "as is", without guarantee or warranty of any kind. Read the full disclaimer here.

When customizing Dynamics 365 forms using JavaScript, there may be a situation in which you want to pass executionContext (or other data) into a web resource or iframe control on the form. For example, you may want to create your own custom HTML button on the form, and have this button perform some operation on the form itself using the formContext object.

In this article, I will be demonstrating how you can use the getContentWindow() method of the Power Apps JavaScript Client API to pass executionContext into a web resource/iframe control on a form.

Overview

The following steps exhibit how you can create a custom HTML button on the Dynamics 365 form that will toggle lock/unlock a field on the form. Please note, this example will only work in the Unified Interface.

Create a custom web resource

First, I will create a custom HTML web resource. This web resource will be very simple, and it will only contain an HTML button in its content window. I will name this web resource “sample_web-resource.html.”

Please see the HTML markup for this web resource below:


    <!DOCTYPE html>
    <html lang="en">
    <head>
        <title>Sample Button</title>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
    </head>
    <body>
        <button id="samplebutton" name="Toggle Field Lock" title="Toggle lock/unlock the field" onclick="ToggleLock()">
        Toggle Field Lock
        </button>

        <script src="sample_web-resource.js" type="text/javascript"></script>
    </body>
    </html>

I will also create a custom JavaScript web resource to go with the above HTML. This web resource will be named “sample_web-resource.js.” Inside this JavaScript, I will create two global variables, parentExecutionContext and parentFormContext that will eventually reference the executionContext and formContext objects from the parent Dynamics 365 form.

Please see the JavaScript code for this web resource below:


    window.parentExecutionContext = null;
    window.parentFormContext = null;

    function InitializeButton(executionContext) {
        // Assign executionContext and formContext to global variables within the web resource
        window.parentExecutionContext = executionContext;
        window.parentFormContext = executionContext.getFormContext();
    }

    function ToggleLock() {
        var fieldName = "name";

        // Get the "name" control from the Dynamics 365 form
        var control = window.parentFormContext.getControl(fieldName);

        // Check if the control is currently locked
        var isLocked = control.getDisabled();
        
        // Toggle the lock on the control
        control.setDisabled(!isLocked);
    }

Add the custom web resource to the Dynamics 365 form

After creating the above two web resources, I will add the “sample_web-resource.html” web resource to the Dynamics 365 form. This component will be added to the form as a web resource control named “WebResource_sample_web-resource.”

For the purposes of this demonstration, I will not walk through the full steps necessary to add this web resource control to the Dynamics 365 form. However, the following official Microsoft Documentation contains some helpful information on this topic: Use IFRAME and web resource controls on a form.

Add JavaScript to the Dynamics 365 form

Now, I will add some JavaScript to the Dynamics 365 form. The following JavaScript code will pass the form’s executionContext object into the custom web resource control that we added to the form. In order to properly work, this JavaScript should be registered on the form’s OnLoad event.

Please see the OnLoad JavaScript code below:


    // This function should be registered on the form's OnLoad event
    function OnLoad(executionContext) {
        // Get formContext
        var formContext = executionContext.getFormContext();

        // Get the web resource control on the form
        var wrCtrl = formContext.getControl("WebResource_sample_web-resource");

        // Get the web resource inner content window
        if (wrCtrl !== null && wrCtrl !== undefined) {
            wrCtrl.getContentWindow().then(function (win) {
                win.InitializeButton(executionContext);
            });
        }
    }

The custom web resource control (“WebResource_sample_web-resource”) can now obtain and use the formContext object to perform operations on the Dynamics 365 form. After saving and publishing the above customizations, the custom HTML button should now lock/unlock the “name” field on the Dynamics 365 form when the button is clicked.

How does this work?

The getContentWindow() Client API method returns a Promise Object. This Promise resolves with a reference to the web resource control’s inner contentWindow object. This inner contentWindow that is returned from the Promise can then be used to access any of the custom web resource’s global variables, functions, objects, etc.

In this simple example, I used the web resource’s inner contentWindow object to pass the form’s executionContext object.

I would like to reiterate that this example will only work in the Unified Interface. A similar outcome may be achieved in the classic web interface using the getObject() method. However, that is outside of the scope of this article.

References

The code used in this article may be found in my GitHub repository at the following link: PassExecutionContextToWebResource.

Additionally, please see the following official Microsoft documentation for more information: