An Introduction to the Widget Format

12:23PM Aug 23rd

↑

↓

A "widget" is simply a single XHTML page: the full power of HTML, CSS and Javascript is available. In addition, extra HTML tags are available to flag preferences and roles required within Frog; and a set of Javascript helper functions are also available to access preferences, make AJAX requests and talk with the Frog API.

The simplest widget

The simplest widget is a standard XHTML page with a frogLib version number (currently 1.1). To render a widget the rendering engine needs to parse the source as XML so your HTML must be well-formed and validate against an XHTML Strict doctype.

<html>
<head>
  <title>My First Widget</title>
  <meta name="frogLib" content="1.1" />
</head>
<body>
  <p>This is my very first widget.</p>
</body>
</html>

The frogLib meta tag is mandatory and indicates which version of the widget compiler you are targeting. The current version is 1.1.

Adding Style and Behaviour

If you wish to include some CSS you can include a <style> tag, or <script> tags for javascript in the <head>. Style rules will apply as you expect, although please namespace your classnames so they do not clash with other elements on a page. Javascript code is supported by a library of helper functions of which we will use the widget.onLoad hook to defined a function that is executed once the widget has loaded.

<html>
<head>
  <title>With Colour and Alerts</title>
  <meta name="frogLib" content="1.1" />
  <style>
  .my-highlighted-text { color:red; }
  </style>
  <script>
  //<![CDATA[
  widget.onLoad = function(){ alert('I work!'); };
  //]]>
  </script>
</head>
<body>
  <p class="my-highlighted-text">This is red.</p>
</body>
</html>

Including preferences

Users of your widget may want to specify their own custom options and other non-sensitive configuration parameters. For this purpose a mechanism to specify widget preferences is provided that is derived from the Netvibes UWA specification. We need to specify the netvibes namespace in our widget and then can include the <widget:preferences> tag containing the preference definitions. For example, if we were writing an RSS reader widget we might specify a user preference field to specify the feed URL:

<!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>
  <title>Rss Reader</title>
  <meta name="frogLib" content="1.1" />
  <widget:preferences>
    <preference type="text" name="feed_url" label="Feed URL"
                defaultValue="http://example.com/feed.rss" />
  </widget:preferences>
  <script>
  //<![CDATA[
  widget.onLoad = function(){
    widget.setBody('<p>You wanted to get the feed URL '+
                           widget.getValue('feed_url')+'</p>');
  }
  //]]>
  </script>
</head>
<body>
  <p>Loading...</p>
</body>
</html>

There are a few aspects to note:

A netvibes namespace needs to be added to the <html> tag (xmlns:widget="http://www.netvibes.com/ns/").
The <widget:preferences> block can then be included, which contains a <preference> element per user preference required.
Preferences can be retrieved by using the javascript widget.getValue method.

The above example gives you a brief idea of how to add user preferences to your widget. To learn more about the different preference types and how to use this data, read our widget preference tutorial.

External Resources

A widget is simply a single XHTML file, so if you need to reference other resources like images or external css or javascript, you need to reference external resources. This is done in the same way as you would expect in an HTML page, although you need to make sure you reference the full URL of external resources as you do not know where this widget will get rendered. For example, a widget that references an external image and CSS file might look something like:

<html>
<head>
  <title>External Resources</title>
  <meta name="frogLib" content="1.1" />
  <link rel="stylesheet" type="text/css"
        href="http://example.com/test.css" />
</head>
<body>
  <img src="http://example.com/test.jpg" 
       alt="test image" />
</body>
</html>

Note the requirement that the widget file validates as well-formed XML requires that all tags be closed: the link and img tags are closed using the shorthand <link /> and <img />.

External Javascript Services

In addition to external resources such as CSS or images, widgets are designed to interact with and use external web services, javascript resources, etc. Often, we just want to pull in an RSS feed or use make ajax requests to external resources. If this is want you want to do, refer to the more detailed tutorials on each subject: Retrieving RSS or Atom feed from a widget and Using Ajax within a widget.

At other times we might want to load and use external javascript libraries, for example say we wanted to perform some translation in a widget we might decide to use Google's translation web service. A simple example widget that performs some translation in this way might look like:

<!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">
  <head>
    <title>Widget with defined styles in head</title>
    <meta name="frogLib" content="1.1" />
    <script type="text/javascript" 
            src="http://www.google.com/jsapi"></script>
    <script type="text/javascript">
    //<![CDATA[
    widget.onLoad = function(){
      google.load('language','1');
      function initialize() {
        var pl = widget.body.getElementsByClassName('payload')[0];
        var text = pl.innerHTML;
        google.language.detect(text, function(result) {
          if (!result.error && result.language) {
            google.language.translate(text, result.language, "fr",
              function(result) {
                var translated = widget.createElement('p');
                translated.addClassName('pass');
                if (result.translation) {
                  translated.setHTML(result.translation);
                }
                widget.addBody(translated);
              });
            }
          });
      }
      google.setOnLoadCallback(initialize);
    };
    //]]>
    </script>
  </head>
  <body>
      <p class="payload">
          This text should become translated into french
      </p>
  </body>
</html>

Interacting With Frog

A widget may need to interact with the Frog platform itself. This can be achieved through the Frog API using javascript. A common task is to retrieve details about the user currently viewing the widget, but if you want to delve further into using the API, read the tutorial about how to write widgets that talk to the Frog API.