Anatomy of a UWA widget

A UWA widget file uses standard XHTML code, except for the preferences section, which uses a specific set of elements. Apart from preferences, the XHTML code is entirely based on Web-standards: XHTML/XML, JavaScript/Ajax, CSS.

The fundamentals

Must-haves

XML: the widget must be made of well-formed XML/XHTML code ;
UTF-8: the widget's file must be encoded in UTF-8 ;
Namespace: the XHTML code must feature the Netvibes widget namespace on the html element, this way: xmlns:widget=“http://www.netvibes.com/ns/”.

Highly recommended

One static file: for better portability, the widget should be made of a single XHTML file, with no server-side code (.htm, .html, .xhtml…). Any dynamic data should be fetched using Ajax methods, and displayed using JavaScript/DOM methods ;
Emulation files: for standalone testing, the widget should make use of the UWA emulation files (described below) ;
No external CSS/JS files: JavaScript and CSS code should be put directly with the widget's XHTML file, using the script and style tags. The only allowed external files are the emulation ones.
Ecosystem: in order to be found by Netvibes users, widget should be submitted to Netvibes Ecosystem. Ecosystem is also where the widget can be compiled for others platforms.

The XML well-formedness is very important, as widgets are rendered through the browser's XML parser. Without it, rendering the widget would be problematic.
The emulation files enable a standalone display of the widget for easier testing. They must be included if you intend to test and debug the widget locally, before submitting it to Netvibes Ecosystem.
Server-side scripting is not recommended for portability reasons: when compiled, the main file is encapsulated into a container, which might not play well with PHP files. Your data should be accessed through Ajax requests to a separate server-side file (PHP, ASP, etc.), which sends back text-based data (feed, JSON, XML, pure text).

The various sections of the XHTML file

File header

Apart from the Netvibes widget namespace, the header features the usual code from any well-formed XHTML 1.0 Strict files.

<?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>
    <title>Title of the widget</title>

The title tag is used to set the actual title of the widget. Its content should therefore be meaningful.

File meta tags

UWA defines a set of new meta labels, used to either describe the widget or to give indication to the platform. They are mostly optional, but very useful.

They are coded just like regular meta tags:

<meta name="author" content="Jane Doe" />

Some platforms require meta tags to be filled, i.e. iGoogle. They are marked accodingly.

Widget meta labels

Name	Role	Content example
author	Name of the widget author. Required by iGoogle	Jane Doe
email	E-mail adress of the widget author. Required by iGoogle	jane@example.org
website	URL of the author's site/page	http://example.org
description	A description of the widget. Required by iGoogle	Access your account directly from Netvibes
version	The widget's version number	0.1 alpha
keywords	Words to categorize the widget	local, food, map
screenshot	Full-size screen-capture of your widget in action. Aim for 280px width. Required by iGoogle	http://example.org/widget-full.png
thumbnail	Smaller version of the thumbnail, or the service's logo. Aim for 120px with by 60px height	http://example.org/widget-logo.png
autoRefresh	Set the time between two refreshing of the widget (in minutes)	20

Platform meta labels

Name	Role	Content example
apiVersion	Version number of the UWA API	1.2
debugMode	If `true` (and if the platform supports it), traces log messages in the platform's JavaScript console (i.e. Firebug)	false

Icons and thumbnails

There are already meta labels for screenshot and thumbnail, but these are only part of the equation.

Favicon

UWA supports favicon, just like any other XHTML file:

<link rel="icon" type="image/x-icon"
  href="http://example.org/widget/favicon.png" />

This icon serves as a quick differentiator within Netvibes: it is display on the top-left side of the widget, next to its title.

The target file should be a classical favicon file:

.ico, .png or .gif (we recommend PNG) ;
16*16 pixels ;
256 colors.

Rich-icon

Some platforms ask for bigger icons. UWA sets this in the same way as the favicon:

<link rel="rich-icon" type="image/png"
  href="http://example.org/widget/richicon.png"/>

This icons serves as a quick differentiator within the following platforms: Apple Dashboard, Windows Vista, Yahoo! Widget. Since it is much more noticeable on these platforms, you should make sure to provide one - which can be a screen capture, a logo, anything that helps differentiate your widget.

Moreover, it you don't provide one, the default UWA icon could lose your widget among all the other UWA widgets that don't define one either. See this blog post for an example.

Emulation files

In order to test your UWA locally, you should add these two lines to your HTML header. They will emulate the UWA environment while not in Netvibes - what we call “Standalone mode”.

Once you are done testing, you can leave them in the code: they are ignored by Netvibes or any supported platform.

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

The emulated environment should not be taken as an exact replica of how UWA widgets behave. The standalone mode offers less constraints than. Therefore, while it is very handy for local testing, only a finale test on Netvibes or a supported platforms can prove the widget to work as expected.

Styling

UWA is based on Web-standards, so widgets can make use of any HTML element and attribute (like table or style, as well as CSS.

But for real styling, widget can rely on CSS. CSS rules are to be defined in the widget file's style tag. Here is an example:

<style type="text/css">
.flickr a, .flickr a:link, .flickr a:hover, .flickr a:active, .flickr a:visited {
text-decoration: none;
border: none;
}
</style>

UWA lets developers use CSS templates for easier styling of some well-known data formatting: data grid, e-mail list, rich list…

It is not recommended to rely on an external CSS file: all CSS rules should be placed in the file's style tag.

It is recommended to only target the widget's element, not general page elements:

no direct use of selectors such as h2, span, div…
better include a widget-specific class to body tag, and target that (as shown in the above sample code. You can use the addClassName() method to dynamically add that class: widget.body.addClassName('flickr');

Scripting

UWA supports scripting using regular JavaScript code. Widget developers can rely on UWA's JavaScript framework for extended functionalities.

Scripts are to be put within a single script tag, inside the file's head section.

UWA lets developers use JavaScript controls for quicker creation of dynamic HTML components: paging, tabs…

It is not recommended to rely on an external JavaScript file: all JS code should be placed in the file's script tag.

It is not recommended to use the document and window objects, as well as their methods, properties and events, for portability reasons. Most of these have been duplicated and expanded in the new widget object.

Preferences

UWA widgets can have user-defined preferences of several types. These preferences are stored on the local platform, and retrieved every time the widget is loaded.

If no preference is set, the widget won't display an Edit menu.

Preferences are based on the UWA-specific widget:preference element, and each preference uses a preferences tag.

There must be only one widget:preferences element per widget in the head portion of the file. There can be as many preference tags as needed, provided they are all within widget:preferences.

Sample preferences block

<widget:preferences>
  <preference name="url" type="text" label="URL" 
    defaultValue="http://feeds.feedburner.com/NetvibesDevBlog" />
  <preference name="limit" type="range" label="Number of items to display" 
    defaultValue="10" step="1" min="1" max="25" />
  <preference name="search" type="hidden" defaultValue="" />
</widget:preferences>

This preferences block gives the following Edit form:

Preference tags

preference tags can use the following types (to be set in the “type” attribute of each tag):

Type	Description	Default value
text	Renders an HTML input field. This is the default type	undefined
boolean	Renders an HTML checkbox (`true` for checked, `false` for unchecked)	false
hidden	Renders nothing, used to initalize a value	(empty)
range	Generates a list of integers inside an HTML listbox (`select`/`option`). Inspired by HTML5's range list	(empty range)
list	Renders an HTML listbox (`select`/`option`)	(empty list)
password	An HTML password field. The password is then saved on our servers, and never sent back to the client	undefined

The list preference type doesn't display properly in standalone mode - you need to test the widget in Netvibes in order to see it properly displayed.

The hidden preference is a handy way to locally store data without letting the user modify it.

Preference attributes

preference tags may contain these attributes:

Attribute	Description
label	Indicates the HTML label describing the preference. Since it is displayed to the user, the value should be short and descriptive
defaultValue	Lets the user set a default value for the preference
min	Defines the minimal integer possible (`range` type only)
max	Defines the maximal integer possible (`range` type only)
step	Defines the incremental step between two values (`range` type only)

Using the list preference tag

Using a preference of type list requires more than three specific attributes, as it does for the range type. The list type requires options, which are to be set like common select/option tags in HTML:

<widget:preferences>
  <preference name="category" type="list" label="Category" 
    defaultValue="1st" onchange="refresh">
      <option value="all" label="all" />
      <option value="1st" label="First category" />
      <option value="2nd" label="Second category" />
      <option value="3rd" label="Third category" />
    </preference>
</widget:preferences>

Notes

Preferences can be retrieved using JavaScript. The UWA JavaScript framework provides a handful of methods for that:

retrieving a preference value: widget.getValue(name), widget.getInt(name), widget.getBool(name) ;
saving a value in a preference: widget.setValue(name, value) (doesn't work with the range and list types).

In order to work properly in iGoogle:

a preference name MUST only contain letters, numbers or underscores - no space.
a preference label MUST be unique: no other preference can use that same label.

In order to work properly on all platforms:

You should not use HTML entities (´, etc) in a preference label: since the file is UTF-8 encoded, you can directly use any special character you need.

You should URL-encode/escape XML special characters in preference values: &, <, >, ' and ” should be respectively rewritten as &, <, >, ", '. This is specially true for preference values that features a URL with a & followed by parameters: use & instead. If the URL already features a &, then encode it to &amp;.

Body section

There is no best way to handle the body section of the XHTML file: developers are free to have their widget start with an empty body, or a fully created one.

Most of the time, developers can rely on this kind of body content:

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

…and update the whole XHTML content using JavaScript and DOM methods from the UWA framework, such as widget.addBody() or widget.body.setHTML.

But another way could be to build a static XHTML skeleton in the body section, and fill the content in using JS/DOM methods.

  (...)
  </head>
  <body>
    <h3>Title goes here</h3>
    <p>The content goes here</p>
  </body>
</html>

In either case, it is recommended to update the content using JS/DOM methods rather than server-side scripting, for portability reasons.