How to integrate ICN with your applications to view content (aka EmbeddedViewerPlugin Part II)

Body

Introduction

In my previous article, I described and provided a sample ICN plugin, and some "entry point" JavaScript as an example of how to integrate the ICN ContentViewer widget generically into any web-based application.

As luck would have it, the journey didn't end there.  In the months that followed, I ended up working with customers to help them take that sample and deploy in the real world.  That process of putting theory into practice presented some challenges to overcome.  Rather than attempt to rewrite the article taking these extra details into account, I have decided to write a short follow-up to discuss those challenges, and how they were addressed.  In taking this approach, it is my hope to keep the initial article as clear and uncluttered as possible, so that its fundamentals are not lost.

Two major hurdles presented themselves that I will discuss.  The first is the issue of "cross-domain" deployment, and the second I will call multi-window coordination in JavaScript.

Cross-domain Deployment

In the situation where you have a web application deployed on "host A", and ICN deployed on "host B", the samples in my original article break down.  Those samples assumed that both the calling application and ICN were on the same host, making it possible for the JavaScript running in the "caller" window to call directly into JavaScript functions in the ICN window.

For security reasons, JavaScript loaded from "host A" cannot make calls to JavaScript loaded from "host B".  To address this, there is a method provided in the JavaScript/DHTML window object, named postMessage.  postMessage is available in most browsers, with the only restriction that I could find being that in IE8, messages must be String type, and cannot be a JavaScript object.

In the sample attached to this article, there is an updated EmbeddedViewerPlugin sample plugin, and two sample HTML files, named XDomainViewerAPI.html and XDomainViewerWindow.html.  As a starting point, both of these would be deployed within the application that will call into ICN.

XDomainViewerAPI.html is the caller, and provides the sample code to use from your application.  The JavaScript functions in this HTML will open a browser window to XDomainViewerWindow.html.

XDomainViewerWindow.html contains "wrapper" JavaScript, and hosts an iframe that takes up the full width and height of the browser window.  The contained iframe opens to ICN.  The wrapper JavaScript uses postMessage to make calls into the contained iframe.

This sample is implemented so that the viewer opens in a separate browser window.  For embedding the iframe, the code in XDomainViewerWindow.html could be copy/pasted to the application page where the iframe would appear, and the wrapper JavaScript functions could then be called directly.

Multi-Window Coordination in JavaScript

With the XDomainViewerAPI.html described in the previous section, a second browser window must be opened and managed.  The time that it takes for the second window to open may vary depending on platform, and the time it takes to load the content of that second window may take varying time as well.  While we can do our best to set up a "handshake" between these windows, there is always some chance that the window will take longer to open than expected, or may not open at all, or may be inadvertently closed by the user.

The caller JavaScript must be implemented to take these possibilities into account.  The code from the original sample was implemented very simply, for illustration purposes, and not so much with production in mind.

The sample attached to this article has been tested and used on customer systems successfully.  There are two important details to point out with it.

First, the handshake to the second window has been set up so that once it is launched, no further attempt is made to launch it a second time, either until the window opens and can be accessed, or the script times out waiting for the window to open.

Second, the code functions that open the window, and obtain the window for calling are all wrapped in try/catch structures.  Any error that occurs in these areas will cause the code to reset its state and start over with opening the browser window.

Additional checks are placed to detect, where possible, when the window has been closed by the user, and logging is added to help with diagnosing issues that may arise.

With the caller code implemented this way, the worst that can happen therefore, is that the script resets itself and starts over - opening a new viewer window.

Conclusion

Other than the items covered in this article, the script contains the same function calls, and works in the same intended fashion as those in the first article.

A zip containing the plugin source and sample HTML pages as discussed in this article can be downloaded here:

https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=e8206aad-10e2-4c49-b00c-fee572815374#fullpageWidgetId=Wf2c4e43b120c_4ac7_80ae_2695b8e6d46d&file=c4a09ee8-aca6-4693-9da5-c584cd62a068