Content of the XHTML file

A UWA widget file is made of a handful of specific parts. Among those are metadata, and the widget:preferences tag.

Widget icons

There are two kinds of icons, each with a different use. They both are defined using a link tag in the widget's header.

If not defined, the widget will fall back to a default UWA icon.

Favicon

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, 16*16, 256 colors. We recommend the PNG format.

<link rel="icon" type="image/x-icon"
  href="http://example.com/widget/favicon.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 this platform, you should make sure to provide one - which can be a screen capture, a logo, anything that helps recognize your widget.

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

The target file should a 128*128 PNG file.

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

Metadata

Metadata are informations stored in the head part of your XHTML file, whose purpose is to describe the widget and define how it works. Those metadata are stored in meta tags, and used as follows:

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

Currently supported metadata are:

Name	Role	Content example
author	Name of the widget author	Jane Doe
website	URL of the author's site/page	http://example.org
description	A description of the widget	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	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
apiVersion	Version number of the API used	1.0
debugMode	If `true` (and if the browser supports it), traces log messages in the browser's console	false
autoRefresh	Set the time between to refreshing of the widget (in minutes)	20

Deprecated metadata:

Name	Role	Reason
inline	Defines how to render the widgets: `true` for inline rendering, `false` for IFRAME rendering. Used for testing purpose.	Has been superseded by the “Render inline” tick-box in the UWA Test Widget

Preferences

Netvibes Mini-Module API modules used “configuration forms” in order to get and set the widget's user settings. UWA (Netvibes API 1.0) replaces configuration forms with the inline widget:preferences tag, which contains preference tags, each defining a possible user setting. The result is the same for the user: the Edit section of the widget is automatically created from these preferences.

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 escape XML special characters in preference values: &, <, >, ' and ” should be rewritten as &, <, >, ", '. This is specially true for preference values that features a URL with a & followed by parameters.

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.

To properly set the widget:preferences tag, your XHTML file MUST feature the following profile declaration:

xmlns:widget="http://www.netvibes.com/ns/"

…like so…

<?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>Widget title</title>
...

The widget:preferences tag is placed in the head part of the static XHTML file, like so:

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

These preferences give the following Edit form:

If you your widget does not use preferences, simply put an empty tag:

<widget:preferences />

Preference tags

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

Type	Description	Default value
text	renders a classic HTML input field. This is the default type	undefined
boolean	renders a HTML checkbox (`true` for checked, `false` for unchecked)	false
hidden	renders nothing, used to initalize a value	(empty)
range	quickly generates a list of integers inside an HTML listbox (`select`/`option`)	(empty range)
list	renders an HTML listbox (`select`/`option`)	(empty list)
password	a HTML password field. The password is then saved on our servers, and never sent back to the client. To be used with the authentication method.	undefined

Please note that the list preference type doesn't display properly in stand-alone mode at the moment - you need to preview it in Netvibes in order to test it properly. We are working to fix it.

The following types are in the works:

Type	Description
textarea	renders a HTML text area

Preference attributes

preference tags may contain other attributes. Here are the supported ones:

Attribute	Description
label	indicates the HTML label describing the preference. Since it is actually displayed, the value should be short and descriptive
defaultValue	lets the user set a default value for the preference
onchange	targets a JavaScript callback `widget` method, fired when the setting is changed. Declaring `onchange=refresh` targets `widget.refresh()`
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:

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

Preferences and JavaScript

JavaScript can be used to get or set values in the preference tags. For this, you have the widget.getValue(name) and widget.setValue(name, value) methods, which respectively let you get and set preference values.

widget.getValue works for all preference tags. In the case of the range or list preferences, it just gets the current selection's value.

widget.setValue is different. It works seamlessly with the text and boolean preferences, but not with the range and list ones. It is not possible as of yet to modify those types using JavaScript, it has to be set directly in the preferences.

Emulation files

In order to test your UWA locally, you must add these two lines to your HTML header. They will emulate the UWA environment while not in Netvibes. You can let them in when submitting to Netvibes. Read ”How to test a UWA widget?”.

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

General scripting and styling

UWA widgets dynamic data are entirely dealt with by JavaScript. Styling is done using CSS. Both of these use the usual script and style tags.

Please note that we do not support external CSS files. Same for external JavaScript files. All your code should be in the main static XHTML file.

<script type="text/javascript">
  // your JavaScript code
</script>
 
<style type="text/css">
 /* your CSS rules */
</style>

You are advised to use the UWA widget object for DOM scripting (read ”Using JavaScript and Ajax in a UWA widget”), and the UWA Templates for proper styling (read ”The UWA templates and controls”).

Body section

As for the content of the body part of the XHTML file, there is no best practice as of yet. You could just put the following:

<p>Loading...</p>

…and update the whole XHTML content using JavaScript and DOM methods. But another way could be to build a static XHTML skeleton (see a sample skeleton) in the body part, and fill the content in using JavaScript, like so:

<h3>Title goes here</h3>
<p>The content goes here</p>

Continue to Using JavaScript and Ajax in a UWA widget…