Export a UWA app into an iframe

You can easily display UWA apps within your own platform, thanks to our UWA.Embedded module. This document will show you how to use UWA.Embedded to display a given app within an iframe on your platform.

Simple usage

UWA provides a JavaScript API to inject your app into an iframe without requiring the full UWA JavaScript Runtime to be loaded into the main document.

1. Inject UWA.Embedded JavaScript file

   <!-- UWA Embedded file -->
   <script type="text/javascript"
    src="//uwa.netvibes.com/lib/c/UWA/js/UWA_Embedded.js">
   </script>

2. Create a container element and put a script tag with UWA.Embedded usage inside it in order to display your app inside this container.

   <!-- UWA Embedded initialisation -->
   <div class="myWidget">
    <script type="text/javascript">
        var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html');
    </script>
   </div>

That's it, your app will display inside an iframe.

Async usage

UWA also provides a JavaScript API to inject your app into an iframe without blocking the loading of your page.

<div class="myWidget">
    <script type="text/javascript">

        var UWA_ASYNC = UWA_ASYNC || [];
            UWA_ASYNC.push({
                url: "http://example.org/apps/mywidget.html",
                options: {}
            });

        (function () {
            var a = document.getElementsByTagName("script"),
                b = a[a.length - 1], c = b.parentNode,
                d = document.createElement("script"),
                e = document.createElement("div");
            e.id = "UWA_ASYNC"; d.type = "text/javascript"; d.async = true;
            d.src = UWA.hosts.uwa + "/lib/c/UWA/js/UWA_Embedded.js";
            c.insertBefore(d, b); c.insertBefore(e, b)
        })();
    </script>
</div>

Advanced usage

UWA.Embedded provide many options in order to control the rendering of the iframe and also remotely control the app or share information with it.

Example to hide the header and footer and use a custom stylesheet:

var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html', {
    displayHeader: false,
    displayFooter: false,
    themeUrl: 'http://example.org/apps/myCustomStyles.css'
});

Example to handle title and preference update:

var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html');

MyApp.addCallback('setTitle', function(title) {
    // setTitle called with value <title>
});

MyApp.addCallback('setValue', function(name, value) {
    // setValue called for key <name> with value <value>
});

Example to configure the app preference values:

var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html', {
    data: {
        myPrefence: 'myValue'
    }
});

Example to update the app preference value and title:

var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html');

// Update widget title
MyApp.setTitle('New Widget title');

// Update widget preference value
MyApp.setValue('myPrefence', 'myValue');

// Send event to the widget
MyApp.sendRemote('onRefresh');

AsyncFrame mode

UWA.Embedded provides a really useful feature called "AsyncFrame". This feature allows a UWA app on the same domain as the page that created the UWA.Embedded instance but still in an iframe.

This means that the UWA app will be able to make Ajax requests directly to your domain without using the Netvibes proxy.

To enable AsyncFrame mode, set the useAsyncFrame option to true:

var MyApp = new UWA.Embedded('http://example.org/apps/mywidget.html', {
    useAsyncFrame: true
});

Warning if you enable this feature be sure that you trust the UWA app that you will render using UWA.Embedded in order to avoid security issues.