UWA one-page documentation

UWA is the Universal Widget API, an XHTML format and JavaScript framework conceived by Netvibes in order to build highly portable widgets, both for Web and desktop platforms.

The present document aims at providing as much information about UWA as possible in a single page.

More detailed information, along with tutorials and examples, can be found on the UWA documentation site.

For any question, check the extensive documentation or visit the Netvibes Developers forum.

Testing a UWA widget

A UWA widget can be tested locally, with the proper UWA look-and-feel, if its code features the two JavaScript and CSS files (see below). This Standalone mode however has its limitations.

A more definitive test can and should be done by putting the file online, and using Netvibes' UWA module, available in Netvibes.com Essential Widget category ; the widget can also be directly added to Netvibes by clicking the Add To Netvibes button found below the widget container when in Standalone mode.

iGoogle testing can be done by displaying the online file and clicking the Add To iGoogle button found below the Add To Netvibes button when in Standalone mode.

Apple Dashboard testing can be done by downloading and installing the UWA Dashboard widget.

Opera testing can be done by downloading and installing the UWA Opera widget.

Currently, no testing widget is available for the other supported platforms.

Installing a UWA widget on widget platforms

Once the widget is added to Netvibes Ecosystem, any user can choose to install on one of the supported Web platform (Netvibes, iGoogle, Live.com, iPhone…), download it on one of the supported desktop platforms (Vista, Apple Dashboard, Opera…).

To submit a widget to Ecosystem, visit http://eco.netvibes.com/submit

Description of a UWA file

A UWA widget basically uses well-known Web standards, such as XHTML, JavaScript and CSS, with a specific XML format for preference portability.

Things to remember

File MUST be encoded using UTF-8.
File MUST be well-formed XML.
File MUST include the Netvibes namespace.
File MUST include a <widget:preference> tag, even empty.
File MUST NOT call external JavaScript or CSS files.
File SHOULD be static XHTML (.html, .xml), with content being updated using Ajax requests and DOM methods.

File header: start of the file

A widget SHOULD begin with the following code.
Meta informations, file title and favicon MUST be adapted to each widget.
A widget SHOULD at least present an “author” meta tag.
All meta tags are optional - although it's better if they are all correctly defined.
The file SHOULD include the JavaScript and CSS emulation files, for basic standalone testing.

The following sample code is informative - do not use as-is, do adapt it to your needs.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" 
  xmlns:widget="http://www.netvibes.com/ns/"  >
  <head>
 
    <meta name="author"      content="John Doe" />
    <meta name="website"     content="http://example.org" />
    <meta name="description" content="A descriptive description" />  
    <meta name="version"     content="0.7 beta 2"
    <meta name="apiVersion"  content="1.0" />
    <meta name="autoRefresh" content="20" />
    <meta name="debugMode"   content="true" />
    <meta name="thumbnail"   content="http://example.org/widget-logo.png" />
    <meta name="screenshot"  content="http://example.org/widget-full.png" />
 
    <link rel="stylesheet" type="text/css" 
      href="http://www.netvibes.com/themes/uwa/style.css" />
    <script type="text/javascript" 
      src="http://www.netvibes.com/js/UWA/load.js.php?env=Standalone"></script>
 
    <title>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.example.com/favicon.ico" />

File header: preferences

UWA preferences are encoded using a specific XML format. This makes it impossible to validate the XHTML code for now, because the XML is not standard. However, XML well-formedness is more important than XHTML validity, so such a validator should only be used for XHTML tags outside of the <widget:preferences> ones.

Preferences MUST use the described options.
Preferences values MUST NOT contain HTML entities (i.e. ”é”), they MUST rely on UTF-8 and use real characters instead (“é”) - this in order not to break the XML parsing.

The following sample code is informative, listing all available types of preferences - do not use as-is, do adapt it to your needs.

<widget:preferences>
  <preference type="text" name="url" label="URL" 
    defaultValue="http://dev.netvibes.com/blog/feed/" />
  <preference type="boolean" name="displayImg" 
    label="Display images" defaultValue="true" />
  <preference type="range" name="limit" 
    step="1" min="1" max="25" defaultValue="10"
    label="Number of items to display"  />
  <preference type="hidden" name="search" 
    type="hidden" defaultValue="" />
  <preference type="list" name="category" 
    label="Category" defaultValue="1st">
      <option value="all" label="all" />
      <option value="1st" label="First category" />
      <option value="2nd" label="Second category" />
      <option value="3rd" label="Third category" />
  </preference>
  <preference type="password" name="authPass" 
    label="User password" />
</widget:preferences>

* A widget that does not need preferences SHOULD at least contain an empty preferences tag.

<widget:preferences />

Preferences MUST be called from JavaScript using one of these methods:

var myVar = widget.getValue(prefName);
var myBool = widget.getBool(booleanPref);
var myNumber = widget.getInt(integerPref);

Preferences can be set/modified through JavaScript (except for the range and list types), using a single method:

widget.setValue(prefName, newValue);

File header: CSS tag

The CSS enclosing tag MUST be valid XHTML.
If no CSS is necessary, the <script> tag SHOULD NOT be included.

The following sample code is informative - do not use as-is, do adapt it to your needs.

<style type="text/css">
  /* This is only a very simple example */
  .myClass {
    color: red;
  }
</style>

File header: JavaScript tags

JavaScript code MUST be triggered from the widget.onLoad method - it's the first method called upon load completion.
JavaScript code SHOULD NOT be triggered from code such as <body onload=“firstFunction();”.
A widget SHOULD make use of the widget.onRefresh event.
Variables SHOULD be local (always use the var prefix when declaring a variable)

NOTE: The document and window objects are not recommended. Most of their methods have been transferred to widget object (see below), while others are not available/recommended anymore.

A full documentation on JavaScript and Ajax use is available. We advise you to read it thoroughly. There also exists a page dedicated to Ajax request samples, to help you build your own.

The following sample code is informative - do not use as-is, do adapt it to your needs. Particularly, the YourWidgetName object's name is to be changed to your likings - this name is not required ; same for variable and argument names, which must be adapted to each situation.

<script type="text/javascript">
// Create a pseudo-namespace for your own JavaScript code.
// Replace 'YourWidgetName' with a unique and informative name.
var YourWidgetName = {};
 
// Here is how you could define a variable named 'myVariable'.
YourWidgetName.myVariable = null;
 
// Here is how you could define a function,
// with one argument, 'anotherVariable'.
YourWidgetName.display = function(anotherVariable) {
  // display code
}
 
// This method will trigger the start of your widget, when the file is loaded.
// This example features an Ajax request using the value of the 'url' preference...
// ...and the YourWidgetName.display() method as a callback.
widget.onLoad = function() {
  UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display);   
}
</script>

Note that the above code uses a potentially unusual way of writing JavaScript code: functions are declared as anonymous, and variables are contained within a JavaScript object (hereby named YourWidgetName). While this coding style is generally recommended to improve readability and lessen the risk of name collision, you can use the coding style you prefer.

JavaScript: The widget & UWA objects

UWA both extends and limits JavaScript, in order to offer more tools to developers, and to ensure that widgets do not interfere with each other.

The document and window MUST NOT be used. Most of their method are available through the widget object.

For more documentation and usage information, check the documentation and examples available at http://dev.netvibes.com/doc/

JavaScript: widget methods

Widget methods

widget.setAutoRefresh() sets the refreshing value - overrides the autoRefresh meta. delay is expressed in minutes

widget.setSearchResultCount() updates the widget's title with a result count, if greater or equal to zero

widget.setTitle() sets the title of the widget - overrides the file's <title> value

widget.setUnreadCount() updates the title with an unread count, if greater or equal to zero

Platform methods

widget.addStar() Netvibes only - triggers Netvibes starring system, in order to add a favorite to the logged user's timeline.

widget.log() logs string in the JavaScript console (provided the browser supports it, i.e. with Firebug, and that debugMode is set to true in the file's meta tags)

widget.openURL() opens a new browser window with the given URL

DOM methods

widget.body returns a reference to the XHTML body content (equivalent to document.body, but limited to the widget)

widget.createElement() create a new DOM element

widget.setBody() sets the body of the widget. Argument must be valid XHTML code. The previous content of the body is erased and replaced by the value of the first argument.

Widget preferences methods

widget.getValue() retrieves the value of the given preference name. Returns a string.

widget.getInt() retrieves the value of the given preference name. Returns an integer.

widget.getbool() retrieves the value of the given preference name. Returns a boolean value (true/false).

widget.setValue() sets name with the value value

JavaScript: widget properties

widget.lang returns the user's language/dialect, depending on his platform settings (default: en_US)

widget.locale returns the user's locale, depending on his platform settings (default: us)

widget.readOnly Netvibes only - returns true if the widget is display within a Netvibes Universe, false otherwise. Used to make sure no code allowing to send data to a private account is displayed.

JavaScript: widget events

The following events should be declared only once, by assigning a function or block of code to them.

widget.onLoad() triggered when the widget is launched - MUST be declared in order for the whole JavaScript code to be lanched

widget.onRefresh() triggered when the widget is refreshed (manually or automatically)

widget.onResize() triggered when the widget is resized

widget.onSearch() triggered when a search is performed within Netvibes

widget.onResetSearch() triggered when the search is reset in Netvibes

widget.onKeyboardAction() triggered when a key is pressed. You can associate specific keys to specific methods

JavaScript: callback events

To be called with widget.callback() (for instance, widget.callback('onUpdateBody');).

onUpdateTitle triggered when the widget's title is modified. Used by widget.setTitle()

onUpdateBody triggered when the widget's content is set or updated. Used by widget.setBody() and widget.addBody()

JavaScript: UWA methods

UWA.$element() Extends hand-created XHTML elements with UWA's element extensions (see below).

UWA.Data methods (Ajax methods)

Full documentation for these Ajax methods is available at http://dev.netvibes.com/doc/

UWA.Data.getFeed(url, callback) gets the content of a feed, in the internal JSON Feed format.

UWA.Data.geJson(url, callback) gets the content of an external data source, in JSON format. The JSON format is the one from the API you call, not the same as the one obtained through UWA.Data.getFeed().

UWA.Data.getText(url, callback) gets the content of an external XML data source, in plain text format.

UWA.Data.getXml(url, callback) gets the content of an external XML data source. It can be used to retrieve the content of a feed in XML format.

UWA.Data.request(url, request object) this is the master data request method, of which the getXml(), getJson() and getText() are shortcuts to.

JavaScript: element extensions

For a given reference 'el' to an XHTML element.

Modifying the element's content

el.addContent() adds content in a div at the end of the element's existing content

el.appendText() adds a new text node at the end of the element's existing content

el.empty() empties the element (equivalent to: el.innerHTML = ””)

el.setText() sets a text node in the element

el.setHTML() sets the HTML content of the element (el.innerHTML equivalent)

el.setContent() empties the element, then fills it with content

el.setStyle() sets the property CSS property, with the value value

Getting the element's DOM info

el.getDimensions() returns a JSON object with 2 properties: width and height, each relating to the element's widht and height

el.getElementsByClassName() returns all the elements that are associated with the given CSS class name

el.getElementsByTagName() returns an array of elements corresponding to the given tag name

el.getParent() return a collection of the element's parent node

el.getChildren() return a collection of the element's child nodes

Modifying the element's display

el.hide() sets the element's display CSS rule to none

el.show() empties the element's display CSS rule

el.toggle() toggles the element's visible CSS rule between hide and show

el.remove() removes the element from the DOM tree

Modifying the element's classes

el.hasClassName() returns true if the element has the given class name as one of its class names

el.addClassName() adds the given class name to the element's existing class names

el.removeClassName() removes the given class name from the element's existing class names