A sample UWA skeleton

The entire sample skeleton

This skeleton should be safe to copy/paste in order to start building your widget. You can get an explanation of every parts in the next section.

Your XHTML file can have any known extension: .htm, .html, xhtml, .xml. Dynamic files (.php, .asp, .rb) are not recommended for portability reasons, but should work on some platforms. Content should be fetched through Ajax requests rather than a reloading of the dynamic file.

JavaScript and CSS code should be put entirely within the file's script and style tags. The entire widget should consist of ONE static file - except for the images, which must be requested using absolute links.

<?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="description" content="A descriptive description" />
 
    <meta name="apiVersion" content="1.0" />
    <meta name="autoRefresh" content="20" />
    <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>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.example.com/favicon.ico" />
 
<!-- Add your UWA preferences as needed -->
    <widget:preferences>
    </widget:preferences>
 
    <style type="text/css">
     /* Add your CSS rules */
    </style>
 
    <script type="text/javascript">
// this is just some sample code
// you can/should delete it all to place your own code instead
 
      // this is how you would declare a global JS object
      var YourWidgetName = {};
 
      // this is how you would declare a global JS variable
      YourWidgetName.yourVariable = "My value";
 
      // this is how you would declare a global 'display()' function
      YourWidgetName.display = function(argument) {
        // display code
      }
 
      // widget.onLoad is the first method called,
      // nothing can be done without it,
      // the rest of the code must be triggered from here.
      widget.onLoad = function() {
        UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display);   
      }
      // you can move your start up code to your own method:
      // simply use widget.onLoad = myObject.myStartupMethod;
    </script>
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

Explanation of the skeleton

This is a cut-up sample XHTML file to get you started using UWA.

Any necessary code for a UWA widget on the client-side is included in a single XHTML file. The following section explains the structure this XHTML file. Details about the metadata and the preferences are to be found in the Content of the XHTML file section.

A widget, and consequently its XHTML file, has several parts:

Header part: declare the metadata, link to UWA files, etc.
Model part: declare the preferences (or properties)
Controller part: define the logic/behavior (JavaScript)
View part (style): define the layout (CSS rules)
View part (structure): define the structure (HTML body)

Widget Header

This is where we define the dependencies (XHTML doctype, character encoding, API files, etc.), the title and the associated icon.

Caution

Widgets MUST be valid and well-formed XML pages. The XML conformity is mandatory because widgets are rendered through the browser's XML parser. XHTML validity is not mandatory - the preference section breaks it.
Widgets MUST be utf-8 encoded. Same for the fetched/displayed content.
Widgets MUST feature the Netvibes namespace in the html tag: xmlns:widget=“http://www.netvibes.com/ns/”.

This section defines

The character encoding used by the widget. *Netvibes only supports UTF-8*.
The cache control (should be public, without expiration date)

<?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 http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta http-equiv="Expires" content="" />

The widget's metadata

<meta name="author" content="John Doe" />
<meta name="description" content="A descriptive description" />
<meta name="apiVersion" content="1.0" />
<meta name="autoRefresh" content="20" />
<meta name="debugMode" content="true" />

The link to the Netvibes style-sheet (CSS)
The reference to the API files (Javascript)

Those two are expected, but are only useful if you intend to test your widget in standalone mode. They provide the whole emulation for the UWA environment.

<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 widget title
The widget icon

<title>Title of the Widget</title>
<link rel="icon" type="image/png" href="http://www.netvibes.com/favicon.ico" />

Widget's preferences

This section defines the preferences (or properties) of your widget. They are defined using XML. Read all about them in Content of the XHTML file section.

Make sure you have the proper UWA profile (xmlns:widget=“http://www.netvibes.com/ns/”) set on your html tag!

The following code is just a sample preference, taken from the RSSReader example. It is in no way mandatory to use the same preferences.

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

If your widget does not need any preference, just use a closed tag:

<widget:preferences />

Widget's behavior

This section defines the logic of your widget. This is the JavaScript section of the file.

The JavaScript code MUST define the widget.onLoad method, from which the rest of the code is called. This method is the first one called when the widget is loaded - so no need for <body onload='myInitMethod()'>, for instance.

For readability purposes, you could store your JS functions and variables in global object (here for instance, var ThisIsMyObject = {};).

<script type="text/javascript">
// this is just some sample code
// you can/should delete it all to place your own code instead
 
      // this is how you would declare a global JS object
      var YourWidgetName = {};
 
      // this is how you would declare a global JS variable
      YourWidgetName.yourVariable = "My value";
 
      // this is how you would declare a global 'display()' function
      YourWidgetName.display = function(argument) {
        // display code
      }
 
      // widget.onLoad is the first method called,
      // nothing can be done without it,
      // the rest of the code must be triggered from here.
      widget.onLoad = function() {
        UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display);   
      }
      // you can move your start up code to your own method:
      // simply use widget.onLoad = myObject.myStartupMethod;
</script>

Widget's styling

This is the Cascading Style Sheet (CSS) section for your widget. You may define any style you need for your widget.

<style type="text/css">
 /* your CSS rules */
</style>
 
</head>

Widget's XHTML structure

This is the XHTML section of your widget. You may define the starting structure of your widget, using standard XHTML tags.

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

Note that the content should be loading using Ajax requests. Accordingly, the XHTML section can be modified/updated through JavaScript/DOM calls. See the available methods in the JavaScript and Ajax documentation.