Pure Client Side Event Exchange between ADF Taskflows and Rich Client Web Applications such as Oracle JET, Angular and React

0

For one of our current projects I have done some explorations into the combination of ADF (and WebCenter Portal in our specific case) with JET. Our customer has existing investments in WC Portal and many ADF Taskflows and is now switching to JET as a WebApp implementation technology – for reasons of better user experience and especially better availability of developers. I believe that this is a situation that many organizations are in or are contemplating (including those who want to extend Oracle EBusiness Suite or Fusion Apps). This is not the ideal green field technology mix of course. However, if either WebCenter Portal (heavily steeped in ADF) or an existing enterprise ADF application are the starting point for new UI requirements, you are bound to end up with a combination of ADF and the latest and greatest technology used for building those requirements.

We have to ensure that the rich client based ‘Portlets’ are nicely embedded in the ADF host environment. We also have to take care that events triggered by user actions in the ADF UI areas are communicated to the embedded rich client based UI areas in the page and lead to appropriate actions over there – and the same for actions in the embedded UI areas and events flowing in the other direction.image_thumb11_thumb

In two previous articles (Publish Events from any Web Application in IFRAME to ADF Applications and Communicate events in ADF based UI areas to embedded Rich Client Applications such as Oracle JET, Angular and React), I have described how events in the embedded area are communicated to the ADF side of the fence and lead to UI synchronization and similary how events in the traditional ADF based UIs are communicated to the embedded areas and trigger the appropriate synchronization. The implementation described in these articles is based on pure, native ADF mechanisms such as server listener, contextual event, partial page refresh in combination with standard HTML5 mechanism for publishing events on embedded IFRAME windows. The route described using these out of the box mechanisms is robust, proven and very decoupled. It allows run time configuration in WebCenter Portal (wiring of taskflows leveraging the contextual event).  This route is also somewhat heavyhanded; it is not very fast – dependencing on network latency to the backend – and it puts additional load on the application server.

There is a fast, light-weight alternative to the use of contextual (server side) events for communication between areas in an ADF based web page. One that can help with interaction between ADF based areas and non-ADF areas (JET, React, Angular) – but also with interactions between two or more pure ADF areas. An alternative that I believe should be part of the native ADF framework – but is not. This alternative is: the client side event bus.

The client side event bus is a very simple pure JavaScript client side component – that I have introduced in an earlier article. In essence, this is what it is:

image

The client side event bus is loaded in the outermost page and will be available throughout the lifetime of the application. It has a registry of event subscriptions that each consist of the name of the event type and a function reference to the function that should be called to handle the event. Each UI area produced from an ADF Taskflow can contain JavaScript snippets that create event handlers (JavaScript functions) and subscribe those with the event bus for a specific event type. Finally, each UI area can publish an event to the event bus whenever something happens that is worth publishing. Of course this is somewhat loosely stated – we should document with some rigor the client side events that each UI area will publish – and will consume – just like the contextual (server side) events with taskflows. It is my recommendation that for the ADF application as a whole, an event registry is maintained that describes all events that can be published – client side or contextual server side – along with the payload for each event.

Let’s make use of this client side event bus for the following use case:

The ADF application embeds a client side web application in an IFRAME in an ADF Taskflow – ADF-JET-Container-taskflow. The application contains a second taskflow – ADF-X-taskflow – that is pure ADF, no embedding whatsoever. The challenge: an event taking place in the client side UI area produced from ADF-X-taskflow should have an effect in the client side web application – plain HTML5 or Oracle JET – in the IFRAME in the UI area produced from the other ADF Taskflow, and we want this effect to be produced as quickly and smoothly as possible and given the nature of the event and the effect there is no need for server side involvement. In this case, using contextual events is almost wasteful – it is not simple to implement, it is not efficient or fast to execute and it does not buy us anything in terms of additional security, scalability or functionality. So let’s use this client side event bus.

The steps to implement – on top of the ADF application with the index.jsf page, the two ADF Taskflows with their respective views and the embedded IFRAME plus web application – are as follows:

(note: all code can be found on GitHub: https://github.com/lucasjellema/WebAppIframe2ADFSynchronize/releases/tag/v3.0)

 

1. Create JavaScript library adf-client-event-bus.js with the functionality to record subscriptions and forward published events to the event handlers for the specific event types

var subscriptions = {};
function publishEvent( eventType, payload) {
   console.log('Event published of type '+eventType);
   console.log('Event payload'+JSON.stringify(payload));
    // find all subscriptions for this event type
   if (subscriptions[eventType]) { 
    // loop over subscriptions and invoke callback function for each subscription
    for (i = 0; i < subscriptions[eventType].length; i++) {
       var callback = subscriptions[eventType][i];
       try {
         callback(payload);
       }
       catch (err) {
           console.log("Error in calling callback function to handle event. Error: "+err.message);
       }
    }//for 
   }//if     
    
}// publishEvent
// register an interest in an eventType by providing a callback function that takes a payload parameter
function subscribeToEvent( eventType, callback) {
   if (!subscriptions[eventType]) { subscriptions[eventType]= [ ]};
   subscriptions[eventType].push(callback);
   console.log('added subscription for eventtype '+eventType);
}//subscribeToEvent

2. Add adf-client-event-bus.js to the main index.jsf page.

        <af:resource type="javascript" source="/resources/js/adf-client-event-bus.js"/>

3. Add client listener to the input component on which the event of interest takes place. In this case: a selectOneChoice from which the user selects a country in view.jsff in taskflow ADF-X-taskflow;

        <af:selectOneChoice label="Choose a country" id="soc1" autoSubmit="false" valueChangeListener="#{pageFlowScope.detailsBean.countryChangeHandler}">
            <af:selectItem label="The Netherlands" value="nl" id="si1"/>
            <af:selectItem label="Germany" value="de" id="si2"/>
            <af:selectItem label="United Kingdom of Great Brittain and Northern Ireland" value="uk" id="si3"/>
            <af:selectItem label="United States of America" value="us" id="si4"/>
            <af:selectItem label="Spain" value="es" id="si5"/>
            <af:selectItem label="Norway" value="no" id="si6"/>
            <af:clientListener method="countrySelectionListener" type="valueChange"/>
        </af:selectOneChoice>

the client listener is configured to invoke a client side JavaScript function countrySelectionListener

4. Add function countrySelectionListener  to the adf-x-taskflow-client.js JavaScript library that is associated with the page(s) in the ADF X taskflow; this function publishes the client side event countrySelectionEvent

function countrySelectionListener(event) {
    var selectOneChoice = event.getSource();
    var newValue = selectOneChoice.getSubmittedValue();
    var selectItems= selectOneChoice.getSelectItems();
    var selectedItem = selectItems[newValue];
    publishEvent("countrySelectionEvent", 
    {
        "selectedCountry" : selectedItem._label, "sourceTaskFlow" : "ADF-X-taskflow"
    });
}

5. Add function handleCountrySelection to the adf-jet-client-app.js JavaScript library that is associated with the JETView.jsff container page in the ADF-JET-Container-taskflow; this function will handle the client event countrySelectionEvent by posting an event message to the IFRAME that contains the client side web application. Also add the call to subscribe this function with the client event bus for events of this type:

subscribeToEvent("countrySelectionEvent", handleCountrySelection);
function handleCountrySelection(payload) {
    var country= payload.selectedCountry;
    var message = {
        'eventType' : 'countryChanged', 'payload' : country
    };
    postMessageToJETIframe(message);
}
//handleCountrySelection

6. Add JavaScript code in view.xhtml in the client wide web app to process an incoming message event of type countryChanged. This event will trigger an update in the UI.

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
        <title>Client Side Web App</title>
        <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cscript%3E%0A%20%20%20%20%20%20%20%20%20%20function%20init()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2F%2F%20attach%20listener%20to%20receive%20message%20from%20parent%3B%20this%20is%20not%20required%20for%20sending%20messages%20to%20the%20parent%20window%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20window.addEventListener(%22message%22%2C%20function%20(event)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20console.log(%22Iframe%20receives%20message%20from%20parent%22%20%2B%20event.data)%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20if%20(event.data%20%26amp%3B%26amp%3B%20event.data.eventType%20%3D%3D%20'countryChanged'%20%26amp%3B%26amp%3B%20event.data.payload)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20var%20countrySpan%20%3D%20document.getElementById('currentCountry')%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20countrySpan.innerHTML%20%3D%20%22Fresh%20Country%3A%20%22%20%2B%20event.data.payload%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20false)%3B%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%2F%2Finit%0A%20%20%20%20%20%20%20%20%20%20document.addEventListener(%22DOMContentLoaded%22%2C%20function%20(event)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20init()%3B%0A%20%20%20%20%20%20%20%20%20%20%7D)%3B%0A%20%20%20%20%20%20%20%20%3C%2Fscript%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object" width="20" height="20" alt="<script>" title="<script>" />
    </head>
    <body>
        
<h2>Client Web App</h2>

        

            Country is 
            <span id="currentCountry"></span>
        

    </body>
</html>

image

 

When the user selects a country using the dropdownlist in area ADF X, the selected country name is displayed almost instantaneously in the IFRAME area based on the rich client web application.

Client Side Event Flow from Embedded Web Application (in IFRAME) to ADF powered Area

Our story would not be complete if we did not also discuss the flow from the embedded UI area to the ADF based UI. It is very similar of course to what we described above. The event originates in the web application and is communicated from within the IFRAME to the parent window and handled by a JavaScript handler loaded for the ADF JET Container Taskflow. This handler publishes a client event with the client side event bus. In this case, a subscription for this event was created from the adf-x-taskflow-client.js library, subscribing a handler function handleDeepMessageSelection that updates the client side message component.

The details steps and code snippets:

1. Add code in view.xhtml to publish a message to the parent window with the message entered by a user in the text field

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
        <title>Client Side Web App</title>
        <!--        <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cscript%20src%3D%22client-web-app-lib.js%22%3E%3C%2Fscript%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object" width="20" height="20" alt="<script>" title="<script>" />-->
        <img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-wp-preserve="%3Cscript%3E%0A%20%20%20%20%20%20%20%20%20%20function%20callParent()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20console.log('send%20message%20from%20Web%20App%20to%20parent%20window')%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20var%20jetinputfield%20%3D%20document.getElementById('jetinputfield')%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20var%20inputvalue%20%3D%20jetinputfield.value%3B%0A%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20var%20message%20%3D%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22message%22%20%3A%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%20%3A%20inputvalue%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2C%22eventType%22%20%3A%20%22deepMessage%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22mydata%22%20%3A%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22param1%22%20%3A%2042%2C%20%22param2%22%20%3A%20%22train%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2F%2F%20here%20we%20can%20restrict%20which%20parent%20page%20can%20receive%20our%20message%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2F%2F%20by%20specifying%20the%20origin%20that%20this%20page%20should%20have%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20var%20targetOrigin%20%3D%20'*'%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20parent.postMessage(message%2C%20targetOrigin)%3B%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%2F%2FcallParent%0A%20%20%20%20%20%20%20%20%3C%2Fscript%3E" data-mce-resize="false" data-mce-placeholder="1" class="mce-object" width="20" height="20" alt="<script>" title="<script>" />
    </head>
    <body>
        
<h2>Client Web App</h2>

        <input id="jetinputfield" type="text" value="Default"/>         
        <a href="#" onclick="callParent()">Send Message</a>
    </body>
</html>

2. Attach message event listener in the JavaScript library adf-jet-client-app.js for the message events (for example from the embedded IFRAME); in this handler, publish the event as a deepMessageEvent on the client side event bus

function init() {
    window.addEventListener("message", function (event) {
        console.log("Parent receives message from iframe " + JSON.stringify(event.data));
        var data = event.data;
        var message = data["message"];

        if (data && message){
        if ( message['eventType'] == 'deepMessage') {
            console.log("ADF JET Container Taskflow received deep message event from web App")
            var message = message.value;
            publishEvent("deepMessageEvent", 
            {
                "message" : message
               ,"sourceTaskFlow" :"ADF-JET-container-taskflow"
               ,"eventOrigin" : "JET:jet-embedded"

            });
        }        }
    },
    false);
}

document.addEventListener("DOMContentLoaded", function (event) {
    init();
});

3. From the adf-x-taskflow-client.js library, subscribe a function as event handler for the deepMessageEvent with the client side event bus

subscribeToEvent("deepMessageEvent", handleDeepMessageSelection);

function handleDeepMessageSelection(payload) {
    console.log("DeepMessageEvent consumed in ADF X Taskflow" + JSON.stringify(payload));
    var message = payload.message;
    // find inputText component using its fake styleClass: messageInputHandle
    //         <af:inputText label="Message" id="it1" columns="120" rows="1" styleClass="messageInputHandle"/>
    var msgInputFieldId = document.getElementsByClassName("messageInputHandle")[0].id;
    var msgInputText = AdfPage.PAGE.findComponentByAbsoluteId(msgInputFieldId);
    msgInputText.setValue(message);    
}

This function extracts the value of the message and sets an inputText component with that value – on the client

 

The end to end flow looks like this:

 

 

image

 

Client Side Interaction with JET application

The interaction as described above with a plain HTM5 web application embedded in an ADF application is not any different when the embedded application is an Oracle JET application. This figure shows an example of a JET application embedded in the JET Client area. It consumes two client side events from the ADF parent environment: countrySelection and colorSelection. It publishes an event itself: browserSelectionEvent. All interaction around these events with the client side event bus is taken care of by the ADF JET Container Taskflow. All interaction between the JET application and the ADF JET Container Taskflow is handled through the postMessage mechanism on the IFRAME’s content window and its parent window.

image

The salient code snippets in the JET application are:

The ViewModel:


define(
    ['ojs/ojcore', 'knockout', 'jquery', 'ojs/ojknockout', 'ojs/ojinputtext', 'ojs/ojselectcombobox'
    ],
    function (oj, ko, $) {
        'use strict';
        function WorkareaViewModel() {
            var self = this;
            // initialize two country observables
            self.country = ko.observable("Italy");
            self.color = ko.observable("Greenish");
            self.browser = ko.observable("Chrome");

            self.callParent = function (message) {
                console.log('send message from Web App to parent window');
                // here we can restrict which parent page can receive our message
                // by specifying the origin that this page should have
                var targetOrigin = '*';
                parent.postMessage(message, targetOrigin);

            }

            self.browserChangedListener = function (event) {
                var newBrowser = event.detail.value;
                var oldBrowser = event.detail.previousValue;

                console.log("browser  changed to:" + newBrowser);
                var message = {
                    "message": {
                        "eventType": "browserChanged",
                        "value": newBrowser
                    }
                };
                self.callParent(message);

            }

            self.init = function () {
                // attach listener to receive message from parent; this is not required for sending messages to the parent window
                window.addEventListener("message", function (event) {
                    console.log("Iframe receives message from parent" + event.data);
                    if (event.data && event.data.eventType == 'countryChanged' && event.data.payload) {
                        self.country(event.data.payload);
                    }
                    if (event.data && event.data.eventType == 'colorChanged' && event.data.payload) {
                        self.color(event.data.payload);
                    }
            } //init

            $(document).ready(function () { self.init(); })
        }

        return new WorkareaViewModel();
    }
);

The View:


<h2>Workarea</h2>


<div>
    <oj-label for="country-input">Country</oj-label>
    <oj-input-text id="country-input" value="{{country}}" ></oj-input-text>
    
<h4 data-bind="text: country"></h4>

    <oj-label for="color-input">Color</oj-label>
    <oj-input-text id="color-input" value="{{color}}"></oj-input-text>
    
<h4 data-bind="text: color"></h4>

    <oj-label for="combobox">Browser Type Selection</oj-label>
    <oj-combobox-one id="combobox" value="{{browser}}" on-value-changed="{{browserChangedListener}}" style="max-width:20em">
        <oj-option value="Internet Explorer">Internet Explorer</oj-option>
        <oj-option value="Firefox">Firefox</oj-option>
        <oj-option value="Chrome">Chrome</oj-option>
        <oj-option value="Opera">Opera</oj-option>
        <oj-option value="Safari">Safari</oj-option>
    </oj-combobox-one>
</div>

 

The corresponding code in the ADF JET client app library:

var jetIframeClientId = "";

function init() {
    window.addEventListener("message", function (event) {
        console.log("Parent receives message from iframe " + JSON.stringify(event.data));
        var data = event.data;
        var message = data["message"];

        if (data && message){
        if ( message['eventType'] == 'browserChanged') {
            console.log("ADF JET Container Taskflow received browser changed event from JET App")
            var browser = message.value;
            publishEvent("browserSelectionEvent", 
            {
                "selectedBrowser" : browser
               ,"sourceTaskFlow" :"ADF-JET-container-taskflow"
               ,"eventOrigin" : "JET:jet-embedded"

            });
        }
    },
    false);
}

document.addEventListener("DOMContentLoaded", function (event) {
    init();
});

function findIframeWithIdEndingWith(idEndString) {
    var iframe;
    var iframeHtmlCollectionArray = document.getElementsByTagName("iframe");
    //http://clubmate.fi/the-intuitive-and-powerful-foreach-loop-in-javascript/#Looping_HTMLCollection_or_a_nodeList_with_forEach
[].forEach.call(iframeHtmlCollectionArray, function (el, i) {
        if (el.id.endsWith(idEndString)) {
            iframe = el;
        }
    });
    return iframe;
}

function processCountryChangedEvent(newCountry) {
    console.log("Client Side handling of Country Changed event; now transfer to IFRAME");

    var message = {
        'eventType' : 'countryChanged', 'payload' : newCountry
    };
    postMessageToJETIframe(message);
}

function postMessageToJETIframe(message) {
    var iframe = findIframeWithIdEndingWith('jetIframe::f');
    var targetOrigin = '*';
    iframe.contentWindow.postMessage(message, targetOrigin);
}

subscribeToEvent("colorSelectionEvent", handleColorSelection);

function handleColorSelection(payload) {
    console.log("ColorSelectionEvent consumed " + JSON.stringify(payload));
    var color = payload.selectedColor;
    console.log("selected color " + color);
    var message = {
        'eventType' : 'colorChanged', 'payload' : color
    };
    postMessageToJETIframe(message);
}
//handleColorSelection


subscribeToEvent("countrySelectionEvent", handleCountrySelection);
function handleCountrySelection(payload) {
    var country= payload.selectedCountry;
    var message = {
        'eventType' : 'countryChanged', 'payload' : country
    };
    postMessageToJETIframe(message);
}
//handleCountrySelection

Resources

Sources for this article: https://github.com/lucasjellema/WebAppIframe2ADFSynchronize. (note: this repository also contains the code for the flows from and to JET IFRAME to and from the ADF Taskflow X via the server side – the traditional ADF approach

Blog Client Side Event Bus in Rich ADF Web Applications – for easier, faster decoupled interaction across regions : https://technology.amis.nl/2017/01/11/client-side-event-bus-in-rich-adf-web-applications-for-easier-faster-decoupled-interaction-across-regions/

Docs on postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director and Oracle Developer Champion. Solution architect and developer on diverse areas including SQL, JavaScript, Docker, Machine Learning, Java, SOA and microservices, events in various shapes and forms and many other things. Author of the Oracle Press books: Oracle SOA Suite 11g Handbook and Oracle SOA Suite 12c Handbook. Frequent presenter on community events and conferences such as JavaOne, Oracle Code and Oracle OpenWorld.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.