Basic UWA skeleton

The skeleton

This UWA skeleton is safe to as a template in order to start building your widget easily, by letting you focus on your own code.

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 using 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 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 - not <body onload="">.
      widget.onLoad = function() {
        // sample Ajax request for a feed, with 'YourWidgetName.display()' used as the callback method
        UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display);   
      }
    </script>
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

Explanation of the skeleton

The skeleton is a XHTML template 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. This section explains the structure the XHTML file.

More details can be found in the Anatomy of a UWA widget section.

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

Header part: declares the metadata, link to UWA files, etc.
Model part: declares the preferences (or properties)
Controller part: defines the logic/behavior (JavaScript)
View part (style): defines the layout (CSS rules)
View part (structure): defines 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

Widget MUST be valid and well-formed XML file. The XML conformity is mandatory because widgets are rendered through the browser's XML parser. However, XHTML validity is not mandatory - the preference section breaks it.
Widget MUST be UTF-8 encoded. Same for the fetched/displayed content.
Widget MUST features 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 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 UWA emulation style-sheet
The reference to the UWA emulation JavaScript

Those two are expected, but are only useful if you intend to test your widget in standalone mode. They provide an emulation of 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 preferences

This section defines the preferences (or properties) of your widget. They are defined using XML. Read all about them in the Anatomy of a UWA widget 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, you can go without the widget:preferences tag.

Widget JavaScript 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 (for instance, var MyGreatWidget = {};).

<script type="text/javascript">
// this is just some sample code
// you should delete it all to place your own code instead
 
      // this is how you would declare a global JS 'YourWidgetName' 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 - not <body onload="">.
      widget.onLoad = function() {
        // sample Ajax request for a feed, with 'YourWidgetName.display()' used as the callback method
        UWA.Data.getFeed(widget.getValue('url'), YourWidgetName.display);   
      }
</script>

Widget CSS styling

This is the Cascading Style Sheet (CSS) section for your widget. You may define any style you need for your widget. You may also rely on UWA templates and controls.

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

Widget 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 methods. See the available methods in the JavaScript documentation and the Ajax documentation.