Universal Widget API (UWA) 1.2

The Universal Widget API is a widget format that aims to be easy to use for Web developers, easy to implement for platform developers, and as portable as possible. To that end, it is based on well-known web technologies, such as XHTML for content, XML for preference handling, JavaScript for behavior, and CSS for styling. It has been designed from the get-go so that Web developers could build a working widget in a manner of minutes, and that platform implementer could quickly have it working for their platform.

In the context of this specification, a widget is defined as a piece of code residing on a Web server that can be embedded into a container prior to being server to the client. That container can either be embedded within a website (for instance, an online widget engine or a simple web page), or exported as single-file archive, compatible with a desktop widget engines.

For this purpose, this specification defines:

a file format, based on XHTML 1.0 Strict,
a preference format, based on XML,
an JavaScript framework, extending the language with useful and proven methods, such as Ajax helper methods.

These three products are expected to work within the constrains of usual web-development: their are no different than the usual format used every day to produce a regular website.

Example of widget

This section is non-normative, but is functional. Its purpose is to get a view of a typical source for a widget.

<?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="Netvibes" />
    <meta name="description" content="Displays latest post from a feed" />
	<meta name="apiVersion" content="1.0" />
	<meta name="debugMode" content="true" />
 
	<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>Latest blog post</title>
	<link rel="icon" type="image/png" href="http://www.netvibes.com/favicon.ico" />
 
	<widget:preferences>
      <preference type="text" name="theFeed" label="RSS/Atom feed to use" 
	    defaultValue="http://blog.netvibes.com/rss.php" />
	</widget:preferences>
 
	<script type="text/javascript">
      var DisplayLatestBlogPost = {};
      DisplayLatestBlogPost.display = function(feed) {
        var latestPost = feed.items[0];
 
        widget.setTitle('<a href="'+feed.htmlUrl+'">'+feed.title+'</a>');
 
        var contentHtml = '';
        contentHtml += '<h2><a href="' + latestPost.link + '">' + latestPost.title + '</a></h2>';
        contentHtml += 'Posted on ' + latestPost.date + '<br />';
        contentHtml += latestPost.content;
        contentHtml += '<em>Read all the previous posts by 
          <a href="' + feed.htmlUrl + '">visiting the blog</a>!</em>'
        widget.setBody(contentHtml);
      }
 
      widget.onLoad = function() {
        UWA.Data.getFeed( widget.getValue('theFeed'), DisplayLatestBlogPost.display );
      }
	</script>

  </head>
  <body>
	<p>Loading...</p>
  </body>
</html>

File format and Conformance

The key words MUST, MUST NOT, SHOULD and MAY in this document are to be interpreted as described in RFC 2119.

UWA is a widget format based entirely on XHTML, CSS, and JavaScript, upon which a couple additions are made:

a namespace: <html xmlns="http://www.w3.org/1999/xhtml" xmlns:"widget=http://www.netvibes.com/ns/">,
a <widget:preferences> element with <preference> tags.

Apart from these specifics, the file-format stays the same as any other well-formed XHTML web page.

A valid UWA widget file follows the following rules:

MUST be made of well-formed XML,
MUST be encoded in UTF-8,
MUST feature the proper namespace if it uses UWA XML preferences element,
SHOULD make use of one of the following extension: .html, .html, .xhtml, .xml.

The XML well-formedness is very important, as widgets are rendered through an XML parser. Without it, rendering the widget would be impossible, as would be compilation for other platforms. As a debugging facility, it is advised for implementers to display an error message instead of the widget if any XML error is found.
Note that no specific DTD is used, so the XML preferences are bound to break XHTML validation. This should not impact on the proper display of the widget.

While it is recommended for a widget to be based on a single static file and to rely on a remote dynamic file for data reading/sending through Ajax requests, the widget developer can choose to rely solely on a dynamically-generated widget based on a series of dynamic files if need be.
Implementations of UWA SHOULD take into account that the widget might be dynamically generated.

Widget preferences

The UWA format should be able to work as-is on any Web- or desktop-platform, as long as it supports standards Web technologies such as XHTML, JavaScript and CSS. Failing that, it has been designed to be easily parse-able thanks to XML, in order to be recompiled into the target platform's specific inner functioning.
Since XHTML doesn't offer any portable solution for preferences handling, UWA defines its own, through an XML extension of XHTML.

The preferences section MUST be placed within the XHTML file's <head> tag.
The preferences MUST be within a <widget:preferences> element.
There MUST be only one <widget:preferences> element per widget.
Each preference MUST be defined within a single <preference> tag within the <widget:preferences> element.
Each preference MUST use a unique value for its “name” attribute. That value MUST NOT already be used as a method name within the UWA JavaScript framework.
The <widget:preferences> element and its content MUST be well-formed XML. Notably, XHTML entities SHOULD be avoided.

Text preference

Format:

<preference type="text" name="url" label="Feed URL" defaultValue="http://dev.netvibes.com/blog/feed/" />

Rendering:
Should be rendered as a standard <input> tag of type “text”, or the platform's equivalent rendering.

Sample rendering:

<label for="m__url">Feed URL:
<input id="m__url" type="text" name="url" value="http://dev.netvibes.com/blog/feed/" /></label>

Boolean preference

Format:

<preference type="boolean" name="displayImg" label="Display images" defaultValue="true" />

Rendering:
Should be rendered as a standard <input> tag of type “checkbox”, or the platform's equivalent rendering.

Sample rendering:

<label for="m__displayImg">Display images:
<input id="m__displayImg" type="checkbox" name="displayImg" checked="checked" /></label>

Hidden preference

Format:

<preference type="hidden" name="searchQuery" type="hidden" defaultValue="" />

Rendering:
Should be rendered as a standard <input> tag of type “hidden”, or the platform's equivalent rendering.
It may also be not rendered at all, and be handled directly by the platform using JavaScript or the platform's own methods.

Sample rendering:

<input id="m__searchQuery" type="hidden" name="searchQuery" />

Password preference

Format:

<preference type="password" name="authPass" label="User password" />

Rendering:
Should be rendered as a standard <input> tag of type “password”, or the platform's equivalent rendering.>

Sample rendering:

<label for="m__authPass">User password:
<input id="m__authPass" type="password" name="authPass" value="" /></label>

List preference

Format:

<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>

Rendering:
Should be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering.

Sample rendering:

<label for="m__category">User password:</label>
<select id="m__category" name="category">
	<option value="all">all
	<option value="1st" selected="selected">First category
	<option value="2nd">Second category
	<option value="3rd">Third category
</select>

Range preference

Format:

<preference type="range" name="limit" 
	step="1" min="1" max="7" defaultValue="5"
	label="Number of items to display"  />

Rendering:
Should be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering.
In case the platform implements an HTML5-enabled Web engine (with Web Forms 2.0 support), the Range preference should be rendered as a standard HTML5 <input> tag of type “number”.

Sample HTML 4 / XHTML 1 rendering:

<label for="m__limit">Number of items to display:
<select id="m__limit" name="limit">
	<option value="1" />1</option>
	<option value="2" />2</option>
	<option value="3" />3</option>
	<option value="4" />4</option>
	<option value="5" selected="selected" />5</option>
	<option value="6" />6</option>
	<option value="7" />7</option>
</select>
</label>

Sample Web Forms 2.0 rendering:

<label for="m__limit">Number of items to display:
<input id="m__limit" name="limit" type="number" step="1" min="1" max="7" defaultValue="5" /></label>

Meta tags

Meta Author

Meta E-mail

Meta Website

Meta Description

Meta Version

Meta API Version

Meta Auto-refresh

Meta Debug mode

Purpose: if true, a call to the widget.log() method SHOULD send the value of the method's first argument to the platform's local console (i.e., Firebug, console, etc.). If false, nothing is done when the widget.log() method is called.
The value of the “content” attribute MUST be a textual boolean value: either “true” or “false”.

Sample usage:

<meta name="debugMode" content="true" />

Meta Thumbnail

Meta Screenshot

Other <head> content

Icon link tag

Rich-icon link tag

Standalone emulation files

While not mandatory, these two files may be added to the widget's <head> section in order to test-drive the widget in standalone mode. They give the widget a basic styling and a basic JavaScript framework.
They therefore only exist for such purpose, and should be entirely ignored by implementing platforms.

Sample usage:

<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">

Note that these are the only two external files that should be linked to or called from the widget's code. Notably, it SHOULD be the only other <script> tag in the whole file, the other one being the one where the widget's JavaScript code resides.

Styling with CSS

JavaScript framework

JavaScript usage

The bulk of JavaScript code used by the widget MUST be placed within its main file - external files SHOULD NOT be called. This may change in future version.
There SHOULD only be one <script> element per widget file.
JavaScript code SHOULD be triggered from the widget.onLoad() method. Note that there are circumstances where the UWA environment may not be fully ready until this event is triggered.
The 'document' and 'window' objects SHOULD NOT be used. Most of their methods/properties are available through the widget object, while others are not available/recommended.
JavaScript code SHOULD NOT be triggered from code such as , but using widget.onLoad(). Those onload arguments will be ignored by the parser and thus likely not triggered.

widget object

UWA events

Widget events

The following events should be declared only once, by assigning a function or block of code to them.
Unless said otherwise, all these events MUST be implemented.

widget.onLoad()
Triggered when the widget is launched.
This event MUST be declared in any widget, in order for the whole JavaScript code to be launched from it.
Implementations MUST trigger this event once the widget is done loading.
If widget.onRefresh() or widget.onResize() are not declared, implementations SHOULD trigger this event instead if the respective triggering events happen.

widget.onRefresh()
Triggered when the widget is refreshed (manually or programmatically).
Implementations SHOULD trigger this event when the DOM is updated through JavaScript, or when new preference values are validated. If this event is not declared, the widget.onLoad() event SHOULD be triggered instead.

widget.onResize()
Triggered when the widget is resized (manually or programmatically).
Implementations SHOULD trigger this event when the size of the widget container is resized (for instance, when the user resizes the containing column, or changes the number of columns on the page). If this event is not declared, the widget.onLoad() event SHOULD be triggered instead.

widget.onKeyboardAction()
Triggered when a key is pressed within the widget's area.
Implementations may first require the user to click within the widget's area in order to limit the interaction to that widget only.
Implementations SHOULD pass the key-code as first argument of the event.

widget.onSearch()
Triggered when a search is performed from within the platform.
Implementing platforms that feature a search form SHOULD trigger this event, with the search query as first argument, so that the widget may use it to further perform a search with its own data, if such thing is possible.
Implementation is not mandatory.

widget.onResetSearch()
Triggered when a search is performed from within the platform is reseted.
Implementations that already implement widget.onSearch() MUST also implement widget.onResetSearch().
Implementation is not mandatory.

Callback events

The following events are for internal use, but a developer can trigger them using widget.callback(): for instance, widget.callback('onUpdateBody');.

onUpdateTitle
To be triggered when the widget's title is modified.
Implementations MUST trigger it when widget.setTitle() is used.
Implementations MAY also trigger for internal reasons.

onUpdateBody
To be triggered when the widget's content is set or updated.
Results in the container being resized (in height) in order to fit the updated display of the widget.
Developers can thus call widget.callback('onUpdateBody') in order to resize the widget.
Implementations MUST trigger it in the following cases:

when widget.setBody() is used,
when widget.addBody() is used.

Implementations SHOULD also trigger it when the preferences are validated.
Implementations MAY also trigger it for internal reasons.

widget methods

Widget methods

widget.setAutoRefresh(delay)
Sets the refreshing value. Overrides the autoRefresh meta, if present. Delay is expressed in minutes.
Argument MUST be expressed as an integer.

widget.setSearchResultCount(count)
If greater or equal to zero, updates the widget's container with a result count. It may for instance add the number next to the title: “(5) Latest blog posts”.
Implementation is not mandatory. SHOULD be implemented if the widget.onSearch() and widget.onResetSearch() events are themselves implemented.
Argument MUST be expressed as an integer.
If argument equals 0, implementations MAY remove the result indicator. For instance, “Latest blog posts” instead of “(5) Latest blog posts”.

widget.setTitle(title)
Sets the disaplyed title of the widget. Overrides the file's <title> tag value.
Triggers the 'onUpdateTitle' callback event.

widget.setUnreadCount(count)
If greater or equal to zero, updates the displayed title of the widget with a count of the widget's items that are still unread by the user. It may for instance add the number next to the title: “(5) Latest blog posts”.
Argument MUST be expressed as an integer.
If value equals 0, implementations MAY remove the result indicator. For instance, “Latest blog posts” instead of “(5) Latest blog posts”.

Platform methods

widget.addStar(data)
Triggers Netvibes starring system, in order to add a favorite to the logged user's timeline.
Argument MUST be a JavaScript object, in the following form:

{
  'title':'The title for the starred link',
  'url':'http://www.example.org/',
  'comment':'user comment about the link'
}

Being Netvibes-specific in nature, this method MAY not be implemented.

widget.log(string)
If the “debugMode” meta tag is set to “true”, SHOULD log the given string to the platform's JavaScript console (i.e. with Firebug).
Equivalent to JavaScript console.log().
Argument MUST be a string.

widget.openURL(url)
Opens a new browser window with the given URL.
Argument MUST be a string containing a valid URL.

DOM methods

widget.body
Provides a reference to the widget's <body> content.
Equivalent to document.body, but limited to the current widget.

widget.createElement(tagName)
Creates a new DOM element.
Equivalent to document.createElement().

widget.setBody(code)
Sets content to the widget's <body> tag.
Argument MUST be a string containing valid XHTML code, or be a DOM node.
The previous content of the body MUST be erased and replaced with the value of the argument.

Widget preferences methods

These methods are specifically built to change the widget's preferences.

widget.getValue(name)
Retrieves the value of the given preference name. Returns a string.
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.getInt(name)
Retrieves the value of the given preference name. Returns an integer.
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.getBool(name)
Retrieves the value of the given preference name. Returns a boolean value (true/false).
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.setValue(name, value)
Sets a preference with the given value.
First argument MUST be an existing preference name.
Second argument SHOULD be a value of a type supported by the preference. If this is not the case, implementations MUST apply a type conversion.

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 displayed within a Netvibes Universe, false otherwise.
Being Netvibes-specific in nature, this method MAY not be implemented.

UWA object

UWA.Data methods (Ajax methods)

Main Ajax method: request()

UWA.Data.request(url, request object)
Gets the content of an external plain-text data source.
First argument MUST be a valid URL, returning data. The returned data SHOULD be textual (plain-text, XML or JSON).
Second argument MUST be a JavaScript object, defining options values for the request.

The request object options are as follows:

'method': 'get' or 'post'. Default is 'post'.
'proxy': 'ajax' or 'feed'. Default is 'ajax'.
'type': 'text', 'xml', 'html' or 'json'. Default is 'text'.
'cache': seconds of server caching. Default is undefined.
'onComplete': name of the callback method. Default is undefined.
'parameters': if 'method' is of type 'post', this option must receive the POST parameters, URL-encoded. Default is undefined.

The object MUST at least explicitly set the onComplete option. The callback method attached to onComplete MUST have one parameter, to receive the content returned by the request. All other options, if not set explicitly, fall back on their respective default setting.

Sample usage:

UWA.Data.request(
  'http://www.example.org/api.php', 
   { 
     method: 'post', 
     proxy: 'ajax', 
     type: 'xml', 
     cache: 3600,
     onComplete: myCallbackMethod,
     parameters: 'firstname=James&lastname=Bond&number=007'
   });

Shortcut Ajax methods: getText()

UWA.Data.getText(url, callback)
Gets the content of an external plain-text data source.
First argument MUST be a valid URL, returning data.
Second argument MUST be a method name, to be called once the data has been properly loaded. That method MUST receive the plain-text data as its first argument.

This method is a short form for the following Ajax call using UWA.Data.request():

UWA.Data.request(url, { method : 'GET', type: 'text', onComplete: callback } );

Shortcut Ajax methods: getXml()

UWA.Data.getXml(url, callback)
Gets the content of an external XML data source.
First argument MUST be a valid URL, returning valid XML data.
Second argument MUST be a method name, to be called once the XML data has been properly loaded. That method MUST receive the XML data as its first argument.
The loaded XML data must remain as valid XML, and should be parse-able using standard XML methods, such as node.childNodes() or node.nodeValue().

This method is a short form for the following Ajax call using UWA.Data.request():

UWA.Data.request(url, { method : 'GET', type: 'xml', onComplete: callback } );

Shortcut Ajax methods: getJson()

UWA.Data.geJson(url, callback)
Gets the content of an external JSON data source.
First argument MUST be a valid URL, returning valid JSON data.
Second argument MUST be a method name, to be called once the JSON data has been properly loaded. That method MUST receive JSON the data as its first argument.

This method is a short form for the following Ajax call using UWA.Data.request():

UWA.Data.request(url, { method : 'GET', type: 'json', onComplete: callback } );

Shortcut Ajax methods: getFeed()

UWA.Data.getFeed(url, callback)
Gets the content of a feed, in the internal JSON Feed format, which is documented here: http://dev.netvibes.com/doc/uwa_specification/uwa_json_feed_format .
Implementations MUST also implement a RSS/Atom feed to JSON Feed format converter, for instance through a specific local proxy.
First argument MUST be a valid URL, returning a valid RSS feed or Atom feed. The method then converts that feed into the internal JSON Feed format.
Second argument MUST be a method name, to be called once the data has been properly loaded. That method MUST receive the JSON data as its first argument.

This method is a short form for the following Ajax call using UWA.Data.request():

UWA.Data.request(url, { method : 'GET', proxy: 'feed', type: 'json', onComplete: callback } );

Element extensions

Modifying the element's content

el.addContent(content)
Adds content in a div at the end of the element's existing content.
Argument MUST be a string or a valid DOM node.
WARNING: this method is deprecated since version 1.2.

el.appendText(text)
Adds a new text string at the end of the element's existing content.
Argument MUST be a string.

el.empty()
Empties the element (equivalent to el.innerHTML = "").

el.setText(text)
Sets a text string in the element.
Argument MUST be a string.

el.setHTML()
Sets the HTML content of the element (equivalent to using el.innerHTML).
Argument MUST be an XHTML node.

el.setContent()
Empties the element, then fills it with content.
Argument MUST be a string or an object. WARNING: this method is deprecated since version 1.2.

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 width and height. For instance:

{ width: 240, height: 140 }

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

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

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

el.getChildren()
Returns 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 display CSS rule between none and an empty value.

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

Modifying the element's classes

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

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

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

Array extensions

Extensions based on JavaScript 1.6

arr.every(callback)
Tests whether all elements in the array pass the test implemented by the provided function.
Returns a boolean.

arr.filter(callback)
Returns a new array with all elements that pass the test implemented by the provided function.

array.forEach(callback)
Executes a provided function once per array element.
array.each works identically.

arr.indexOf(item, from)
Returns the first index at which a given element can be found in the array, or -1 if it is not present.
Returns an integer.

arr.map(callback)
Returns a new array with the results of calling a provided function on every element in this array.

arr.some(callback)
Tests whether some element in the array passes the test implemented by the provided function.
Returns a boolean.

Compatibility extensions

arr.equals(compare)
Test wether the array equals to the one passed as parameter.
Returns a boolean.
Needed for compatibility with a third-party UWA implementation.

arr.detect(iterator)
TODO: document this extension.
Needed for compatibility with the TabView Control.
Needed for compatibility with the MultipleFeeds native widget.

arr.normalize(sum)
TODO: document this extension.
Needed for compatibility with a third-party UWA implementation.

String extensions

Utility extensions

str.escapeRegExp()
Returns the string with escaped regular expression characters.
Needed for compatibility with Vibes native widget.

str.isEmail()
Tests wether the string uses a valid e-mail format.
Returns a boolean.
Needed for compatibility with a third-party UWA implementation.

str.stripTags()
Strips a string of any HTML tag.
Returns the cleaned-up string.

str.trim()
Trims the leading and trailing spaces off a string.
Returns the trimmed string.
Needed for compatibility with a third-party UWA implementation.

str.truncate(length, suffix)
Truncates a string to the given length and appends a suffix to it (indicating that it is only an excerpt).
Returns the truncated string.
Needed for backward compatibility with a third-party UWA implementation.

Internal/compatibility extensions

str.camelCase()
TODO: document this extension.
Returns a string.
Used in el.setStyle implementation in Element.js.

str.contains(string, separator)
TODO: document this extension.
Returns a string.
Used in el.hasClassName implementation in Element.js.

str.format()
TODO: document this extension.
Returns a string.
Needed for compatibility with various Netvibes native widget (new format).

str.makeClickable()
TODO: document this extension.
Returns a string.
Needed for compatibility with various Netvibes native widget.

str.parseRelativeTime(date, offset)
Returns the time elapsed between the given date and now, ie. “about 3 hours ago”.
Returns a false boolean if the first argument is not in the “2008-01-01 23:56:47” format, otherwise it returns a string.
Needed for Timeline Control.

str.s()
TODO: document this extension.
Returns a string.
Needed for compatibility with various Netvibes native widget.

str.unescapeHTML()
TODO: document this extension.
Returns a string.
Needed for compatibility with various Netvibes native widget.