"Hello World" using UWA

There are many ways to reach a given result. This page presents you with 4 successive versions of a widget that simply display the “Hello World” message. With each version, you will learn something new about UWA:

Step 1: Using static content

This will use a basic UWA file. It will display the text in the body tag, just as any Web page would do.

Note that a UWA file has 3 main characteristics:

  1. MUST feature the correct namespace in the html tag
  2. SHOULD feature the emulation JS and CSS files, so that in standalone mode (outside of Netvibes), the widget uses the UWA environment and look-and-feel.
  3. SHOULD feature an empty widget:preferences tag
<?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" />
 
    <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>
 
    <widget:preferences />
 
    <title>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.netvibes.com/favicon.ico" />
 
  </head>
  <body>
    <p>Hello world !</p>
  </body>
</html>

Step 2: Using preferences

You can define a preference that the user will be able to edit. This is done using the UWA's <widget:preferences> element.

In this example, one preference is defined, named hellowho: a text string that the user can edit to put his name.

You can access a preference using UWA's JavaScript methods like widget.getValue(name) or widget.setValue(name, value). Values are stored on the Netvibes server or in a cookie, depending of the platform.

To get the value of the hellowho preference, you must use widget.getValue('hellowho').

Read about using JavaScript/Ajax in UWA, and about the content of a XHTML file, including metadata and preferences. 

<?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="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>
 
    <widget:preferences>
      <preference name="hellowho" type="text" label="Hello who ?" 
        defaultValue="World" />
    </widget:preferences>
 
    <title>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.netvibes.com/favicon.ico" />
 
    <script type="text/javascript">
      // widget.onLoad() is fired when the widget is fully loaded
      // or when the preferences are validated 
      widget.onLoad = function() {
        var who = widget.getValue('hellowho');
        // widget.setBody() replaces the content of the body element
        widget.setBody('<p>Hello ' + who + '!</p>');
      }
    </script>
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

If the user enters “Richard” instead of “World” in the preference, the message will be updated accordingly when the widget is validated.

Step 3: Retrieving data through an Ajax request

You can easily interact with an API, wether it is your own or an open API.

If you don't have an API yet, it is very easy to get one: just build a server-side, dynamic file (PHP, ASP, etc.) that would respond to certain requests with the appropriate data, packaged in one of the supported formats: XML, JSON, HTML or plain text.

Let's say you already have an API, which sends back the plain text answer ”World” to any request. This service would be located at http://example.org/api.php. Remember that the data sent to and retrieved from the widget MUST be UTF-8 encoded.

The appropriate UWA method in this case is UWA.Data.getText(), as documented in ”Using JavaScript/Ajax in UWA”. Here is how the code source of the widget could look like… 

<?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="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>
 
    <widget:preferences>
      <preference name="hellowho" type="text" label="Hello who ?" 
        defaultValue="World" />
    </widget:preferences>
 
    <title>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.netvibes.com/favicon.ico" />
 
    <script type="text/javascript">
      var HelloWidget = {
        toWhom: "no one",
 
        parse: function(who) {
          if (who) HelloWidget.toWhom = who;
          widget.setBody('<p>Hello ' + HelloWidget.toWhom + '!</p>');
        }
      }
 
      widget.onLoad = function() {
        // the URL should return 'World' in plain text
        UWA.Data.getText('http://example.org/api.php', HelloWidget.parse);
      }
    </script>
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

Note that we chose here to create a HelloWidget JSON object to store our methods and variables. This is not mandatory, you can use common JavaScript if you like. Just remember to always prefix your variables with the var keyword.

Explore the other available Ajax methods in order to find the one that fits your needs - and those of your API.

Step 4: sending data with Ajax

Once you know and understand UWA's Ajax methods, you might want to not only receive content, but also send data - and possibly get new content in exchange.

The body part of the widget is preferably used for display content, not forms. Therefore, the data your user will send to your server should be entered through the Edit part of the widget. Any change to the preference will immediatly update the widget. Also, the data entered by the user will be stored by UWA, so that next time he uses your widget, it is using the user's data rather than the default one.

Let' say you web service simple takes the data being sent to it using an HTTP GET request, and returns it within the proper ”Hello XXX !” string. Again, all UTF-8, all the time… 

<?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="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>
 
    <widget:preferences>
      <preference name="hellowho" type="text" label="Hello who ?" 
        defaultValue="World" />
    </widget:preferences>
 
    <title>Title of the Widget</title>
    <link rel="icon" type="image/png" 
      href="http://www.netvibes.com/favicon.ico" />
 
    <script type="text/javascript">
      var HelloWidget = {
        toWhom: false,
 
        parse: function(toWhom) {
          if (toWhom) HelloWidget. toWhom = toWhom;
          widget.setBody('<p> Hello ' + HelloWidget. toWhom + '!</p>');
        }
      }
 
      widget.onLoad = function() {
        var url = 'http://example.org/api.php?hello=' + widget.getValue('hellowho');
        UWA.Data.getText(url, HelloWidget.parse);
      }
    </script>
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

If you'd rather use POST rather than GET, you can of course do it easily with UWA. Check the available options for ''Ajax.request''.

Step 5: jump to bigger things

See How to build a RSS reader to dive deeper in JavaScript in the UWA environment, with a fully working widget. Also, read through our HOWTOs and try our examples.