[Engine-devel] New feature in UI Plugins available: Cross-window communication support

[Vojtech Szocs]

Hello everyone,

we just introduced support for cross-window (cross-origin, a.k.a. cross-domain) communication that can be utilized by UI plugins.

Custom content contributed by the UI plugin (e.g. via tab or dialog) can send arbitrary messages back to given plugin(s) via WebAdmin (parent) window. The implementation is based on HTML5 window.postMessage API that triggers 'message' events on the target window. WebAdmin takes care of intercepting such messages, performing source origin check per each plugin, and passing message data to plugin(s) as appropriate.

With this feature, custom content can directly and transparently control/notify given UI plugin(s). Aside from content --> plugin message passing, the message data received by the plugin also contains reference to source window, i.e. custom content that sent the message. This can be used to establish two-way communication between custom content window and plugin code.

For example, custom HTML content contributed by the plugin uses JavaScript to send the message:

    // 'parent' refers to WebAdmin window.
    // Most browsers support sending String messages, e.g. 'Foo Bar'.
    // Modern browsers support sending Object messages, e.g. {'foo':'bar'}.
    // The second argument is target origin that should match WebAdmin (Engine) origin.
    // You can also use '*' (any origin) as per HTML5 spec, however this is not a good practice.
    parent.postMessage('Foo Bar', 'http://engine-host:1234');

Sample UI plugin that receives the message:

<snippet>

    var api = parent.pluginApi('showcase');

    // New bootstrap sequence function: provide custom API options object.
    // This is completely optional, there are always sensible fallback values.
    api.options({

        // Specify allowed source origin(s) from which messages will be accepted.
        // Can be either string (single origin) or string array (multiple origins).
        // Can be '*' (any origin) as per HTML5 spec, however this is not a good practice.
        // Default value is empty array (reject all messages).
        allowedMessageOrigins: ['http://content-host:80','http://content-host:443']

    });

    api.register({

        UiInit: function() {
            // Assume the dialog content takes care of sending the message.
            api.showDialog(...);
        },

        // New event handler function: process message event.
        // Called *only* after passing source origin check, based on 'allowedMessageOrigins'.
        MessageReceived: function(data, sourceWindow) {
            // Parse and interpret data
            // Optionally, interact with sourceWindow (content that sent the message)
        }

    });

    api.ready();

</snippet>

Attached you can find a sample UI plugin that demonstrates this new feature via custom dialog.

Regards,
Vojtech
-------------- next part --------------
A non-text attachment was scrubbed...
Name: sample-cross-window-messaging-plugin.tar.gz
Type: application/x-compressed-tar
Size: 881 bytes
Desc: not available
URL: <http://lists.ovirt.org/pipermail/devel/attachments/20130412/f70eec26/attachment-0001.bin>