Developers

You are here: Home » Universal Widget API » tutorials » "Hello World" using UWA

"Hello World" using UWA

"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 displays the “Hello World” message. With each version, you will learn something new about UWA:

Using static content
Using preferences
Retrieving data with Ajax
Sending data with Ajax

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 2 main characteristics:

MUST feature the correct namespace in the html tag
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.

<?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>
 
    <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 in.

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

This way, if the user enters “Richard” instead of the default “World” in the preference, the message will be updated accordingly when the preference is validated.

Step 3: Retrieving data through an Ajax request

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

If you don't have access to an API yet, it is very easy to build one for test purposes: 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 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>

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 from a server, but also send data to that server - and possibly get new content in exchange.

The body section of the widget is preferably used for display content, not forms - although anything is possible. 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 immediately update the widget.

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's say your web service simply 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.

Print
Send to a friend
Add to favorites
Last modified: 2008/10/29 12:50

Documentation

Developers

Quick links

Subscribe

"Hello World" using UWA

Step 1: Using static content

Step 2: Using preferences

Step 3: Retrieving data through an Ajax request

Step 4: sending data with Ajax

Step 5: jump to bigger things

Business

Developers

Community

Press