Back to my page

Developers

You are here: Home » Universal Widget API HOWTOs » UWA IFrame method
Table of Contents

UWA IFrame method

You can easily display UWA widgets within your own environment, thanks to our IFrame method. This document will show you how to build the correct URL to display in an IFrame on your site - which is the easiest way to stay secure. There can be any number of IFrames, as long as each frame has a unique ID (related to the widget's chosen ID)

What this method doesn't provide:

  1. drag&dropping for your system
  2. tool to convert widget preferences into a form adapted to your system

How to build the IFrame's target URL

  • The base IFrame URL is:
http://nvmodules.netvibes.com/widget/frame/
  • You have to indicate the UWA widget URL (urlencoded). In this example, we generate a URL for the Nevibes Alexa sample widget:

Original widget URL: 

http://www.netvibes.com/api/uwa/examples/alexa.html

URL-encoded widget URL: 

http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html

Resulting URL: 

http://nvmodules.netvibes.com/widget/frame/?uwaUrl=http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html
  • You must pass a widget identifier. It should be unique to the page, and generated by your system. For example, with id=123456:
http://nvmodules.netvibes.com/widget/frame/?uwaUrl=http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html&id=123456
  • In order for the widget's height to be correctly resized when its content gets displayed, you must add a reference to a local proxy file (such as the one provided by Netvibes). This file must be hosted on the same domain as the page where the IFrame is set. The attribute is called ifproxyUrl (for “IFrame proxy URL”).

For instance, if your widget is displayed here: 

http://www.example.com/myWidgets/index.html

In that case, the proxy file could reside here: 

http://www.example.com/myWidgets/proxy.html

Once the URL is encoded, the string for this example would be like so: 

&ifproxyUrl=http%3A%2F%2Fwww.example.com%2FmyWidgets%2Fproxy.html

Which would result in this IFrame URL. 

http://nvmodules.netvibes.com/widget/frame/?uwaUrl=http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html&id=123456&ifproxyUrl=http%3A%2F%2Fwww.example.com%2FmyWidgets%2Fproxy.html
  • Then, if needed, you can set the widget's preferences:

In our example, the Alexa widget can take up to 5 sites, with variables names being “alexaSite0” to “alexaSite4”. We'll compare two site: alexaSite0 → netvibes.com & alexaSite1 → nytimes.com

Resulting IFrame URL: 

http://nvmodules.netvibes.com/widget/frame/?uwaUrl=http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html&id=123456&ifproxyUrl=http%3A%2F%2Fwww.example.com%2FmyWidgets%2Fproxy.html&alexaSite0=netvibes.com&alexaSite1=nytimes.com
  • Finally, just add the URL to an IFrame on your page. The IFrame should have the identifier in its 'id' attribute, in the form “frame_{ID}”, with ID being your widget's unique identifier:
<iframe id="frame_123456" scrolling="no" frameborder="0"
  height="200" width="400"
  src="http://nvmodules.netvibes.com/widget/frame/
  ?uwaUrl=http%3A%2F%2Fwww.netvibes.com%2Fapi%2Fuwa%2Fexamples%2Falexa.html
  &id=123456
  &ifproxyUrl=http%3A%2F%2Fwww.example.com%2FmyWidgets%2Fproxy.html
  &alexaSite0=netvibes.com&alexaSite1=nytimes.com">
</iframe>

…and you are done with the IFrame itself!

How to display the widget in the correct height (and other widget communication issues)

The IFrame code should be placed with the <body> of a standard XHTML page. In order for the widget to properly communicate with your system, you not only need to place a proxy file on your host, as already advised, but you also need to place JavaScript code within the page itself. This code will let you completely handle the various messages sent by and to the widget, one of the most important being the resizing message.

Here is the basic code on which to build upon. As-is, it should handle resizing automatically. 

<script type="text/javascript">
if (typeof UWA == 'undefined') UWA = {};
UWA.MessageHandler = function(message) {
  var id = message.id;
  switch (message.action) {
    case 'resizeHeight':
      var frame = document.getElementById('frame_' + id);
      if (frame) {
        frame.setAttribute('height', message.value);
      }
      break;
   default:
      console.log(message.action + ': not implemented - ' + message.name + ':' + message.value);
      break;
  }
};
 
</script>

This code creates a message-handler for all messages coming from the running widgets. The UWA.MessageHandler() method is called by the widget with a JSON object as a message. This message contains the following properties:

  1. id: the widget's ID, as declared in the IFrame URL.
  2. action: the name of the action. There are a handful, listed below.
  3. value: the action's value.
  4. name: if needed, the name of the target to which the value applies. If not used, its value is 'false'.

For instance, in the above sample code, we have built a handler for the 'resizeHeight' action, which is triggered when the widget is first display, or when its content is update. It asks for the container to resize itself according to the displayed content's height, which is given in the action's value. Once the widget's frame has been found (it's ID should be of the form frame_{ID}, as indicated before, the widget's height is reset to the required value.

In this sample code, only the 'resizeHeight' action is describe, in order for you to get the idea of the way it works. Other actions are redirected to the default behavior, which as you can see is to display a message in the console. In our own version of this code, you can make it do whatever is need by your website to react consistently.

The full set of available actions is as follows:

action description
setTitle can be used to change the widget's title, as displayed by your website
setValue can be used to update the widget's preference value
addStar can be used to indicate that the URL has been correctly sent to Netvibes
setIcon can be used update the widget's favicon
setUnreadCount can be used indicate the number of unread messages. usually place beside the title
setSearchResultCount can be used indicate the number of results for a search with the widget's content. usually placed beside the title

The 'switch' section of the above code can therefore be customized according to your needs and possibilities. For instance, here we set an aditionnal method for the 'setTitle' action: 

(...)
switch (message.action) {
   case 'resizeHeight':
      var frame = document.getElementById('frame_' + id);
      if (frame) {
        frame.setAttribute('height', message.value);
      }
      break;
   case 'setTitle':
      var chrome = document.getElemnetById('widget-' + id);
      var title = chrome.getElementsByClassName("title")[0];
      if (title) {
         title.innerHTML = message.value;
      }
      break;	
   default:
      console.log(message.action + ': not implemented - ' + message.name + ':' + message.value);
      break;
  }
(...)

Quick FAQ

Q: Where can I find the “proxy.html” file that is mentioned that you mention to enable auto-resize?
A: Here it is.

Q: Where should I put the “proxy.html” file you provide us with?
A: It should be uploaded on your own domain.

Q: You mention a unique ID for each widget. Who provides it? The user? Your system? Our system?
A: The widget ID has to be unique to the current page, and handled/generated by your system. All you will need from us is the widget's URL, provided by Ecosystem (or from a list of selected widgets).

Q: How can I implement drag&dropping on UWA widgets?
A: It all depends on your own system. Widgets are hosted in an IFrame, so you will need to build a drag&drop functionality for your system if you don't have one already, and make it work with iframed UWA widgets.

Business

Partner with us.

Developers

Build once, run everywhere.

Community

Get involved, get localized.

Press

News. Media kits. Press releases.