Converting a MiniAPI module to a UWA widget (part 1)
The Universal Widget API has been available since March 9th, 2007 now, and it was released roughly one year after we launched MiniAPI. MiniAPI has been a huge success, but it was superseded by UWA, and got deprecated on July 9th, 2007 - that is, it is no longer possible to submit a MiniAPI module on Ecosystem.
Unfortunately, even though both MiniAPI and UWA are easy to implement and closely related, most of the MiniAPI modules in Ecosystem have not yet been converted to UWA. We did document how to convert MiniAPI JavaScript calls into proper UWA ones, but it might still be lacking a few tips and tricks.
So here goes: a checklist/walkthrough of the conversion of one MiniAPI module into a UWA widget. For this first part, we’ll be overseeing the conversion of a simple “Hello World!” module, straight out of the MiniAPI step-by-step documentation (which is deprecated and not to be used anymore).
In any case, remember that a UWA widget is little more than a classic XHTML, with a few constrains added to make sure it’s portable (notably the preferences). So, if you know how to code a website, you know how to code a UWA widget 
Converting the Hello World module in UWA
It’s really simple once you know the classic UWA skeleton. Here’s a piece by piece comparison of the modules’s code, and the resulting UWA code.
File’s header
MiniAPI:
<!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">UWA:
<?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/" >At first sight, not much of a difference. The UWA version features the XML prolog, to assert that we insist (we really do) on XML well-formedness. Note, however, the supplementary XML namespace: xmlns:widget="http://www.netvibes.com/ns/". Don’t put it, and your widget won’t be recognized as UWA.
<head> section: title and classic metas
MiniAPI:
<head>
<title>Hello world</title>
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8" />UWA:
<head>
<title>Title of the Widget</title>
<link rel="icon" type="image/png"
href="http://www.netvibes.com/favicon.ico" />
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8" />
<meta http-equiv="Expires" content="" />No real difference here. The “Expires” meta was not added in MiniAPI’s documentation for shortness, but it is also existed there.
Likewise, the icon link-tag was available in MiniAPI, but wasn’t added in the doc for the same reason.
<head> section: UWA metas
UWA:
<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" />These meta tags are new to UWA, and serve various purpose.
For instance, MiniAPI developers used to put their name, their website and the widget’s version number into the modules’s configuration form. Since the preference form is not as flexible in UWA for portability reasons, these pieces of information have been moved to meta-tags with specific names, such as author, version and website. All meta tags are explained in the doc.
Note that the debugMode is especially useful, since when set to true, you can log texts and variables into the local console (for instance, Firebug in Firefox) using widget.log(something). If set to false, widget.log(something) doesn’t output anything anywhere.
<head> section: emulation files
MiniAPI:
<link rel="stylesheet" type="text/css"
href="http://www.netvibes.com/api/0.3/style.css" />
<script type="text/javascript"
src="http://www.netvibes.com/api/0.3/emulation.js"></script>
</head>UWA:
<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>
</head>Same usage, updated URL. Don’t mix the two: your widget would still work, but you’ll miss much of the cool UWA functionalities when testing in standalone mode.
<body> section
MiniAPI:
<body>
<p>Hello world!</p>
</body>
</html>UWA:
<body>
<p>Hello world!</p>
</body>
</html>No difference whatsoever!
Well, the original UWA skeleton features <p>Loading...</p> instead of <p>Hello world!</p>, but that’s an example: if you don’t update the widget’s body using JavaScript/DOM methods, you can put any static text content you want in the body. Remember, a UWA widget is merely a XHTML page, only smaller
That’s it for the converstion basics. In the second part of this series, we’ll talk about converting a widget with a configuration form, which is one of the biggest and most important change in UWA.
Tags: conversion, emulation files, helloworld, miniapi, uwa
netvibes