Netvibes mini API Step by Step

This version of the API is not recommended anymore, it has been superseded by the UWA.

While it might still work, we highly recommend to transition to the new Universal Widget API.

Last update: 14/04/2006

Let's start learning building HTML API Modules.

STEP 1: Hello world !

For example, we can write a famous “hello world” example simply like this:

<!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 profile="http://www.netvibes.com/api/0.3/profile">
  <title>Hello world</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
</head>
<body>
  <p>Hello world !</p>
</body>
</html>

Test this module: http://www.netvibes.com/api/0.3/examples/example1.html

Note that:

Netvibes Html Modules SHOULD be XHTML strict and well formed
Netvibes Html Modules SHOULD be utf-8 encoded

How it works:

The title of the XHTML page appear in the module title bar
The content into the body of the XHTML page appear in the module content area.

STEP 2: Emulate Netvibes Rendering

To make module developement more easy, you can add CSS and Javascript to your module. It will help you see how it will be rendered into Netvibes.

Add this two lines into your html HEAD section:

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

This preview functionnality is very minimal for the moment and it may evolve in further versions.

Test this module: http://www.netvibes.com/api/0.3/examples/example2.html

STEP 3: Multiple Pages

You can create and link multiple pages to build your netvibes module ! Simply make relative hyperlinks between the pages. Absolute links will be considered external and opened in a new window.

<!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 profile="http://www.netvibes.com/api/0.3/profile">
  <title>Hello world</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
</head>
<body>
  <p>Hello world!</p>
  <p><a href="http://www.netvibes.com/api/0.3/examples/example3-page2.html">Here's 
    the link pointing to page 2</a></p>
 
</body>
</html>

Test this module: http://www.netvibes.com/api/0.3/examples/example3-page1.html

STEP 4: Mark Up

You can use all the markup available in XHTML strict. In theory, all must be rendered very gracefully with the “Netvibes Touch” ™ thanx to our CSS.

Let's try a combination of all we can do:

<!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 profile="http://www.netvibes.com/api/0.3/profile">
  <title>Hello world</title>
 
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <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>
<body>
  <h1>Testing Markup</p>
 
  <p>This is a paragraph. You can add <b>bold</b>, <strong>strong</strong>, 
    <em>em</em>, and <i>i</i>.</p>
 
  <p>And just bellow one other.</p>
  <h2>Lists</h2>
  <h3>Unordered lists</h3>
  <ul>
 
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
  <h3>Ordered lists</h3>
 
  <ul>
    <li>Item foo</li>
    <li>Item bar</li>
  </ul>
  <h2>Tables</h2>
 
  <table class="center border large">
    <tr>
      <th>Col 1</th>
      <th>Col 2</th>
 
      <th>Col 3</th>
    </tr>
    <tr>
      <td>4</td>
      <td>2</td>
 
      <td>8</td>
    </tr>
  </table>
  <h2>Forms</h2>
  <form action="" method="">
 
    <fieldset>
      <label for="url">URL</label>
      <input name="url" id="url" type="text" value=""/>
 
      <label for="title">Title</label>
      <input name="title" id="title" type="text"  value=""/>
 
      <label for="description">Description</label>
      <textarea name="description" id="description" rows="5" cols="30">
      </textarea>
 
      <input name="add" type="submit" value="Ok"/>
    </fieldset>
  </form>
 
</body>
</html>

Test this module: http://www.netvibes.com/api/0.3/examples/example4.html

STEP 5: Classic forms

Like we just saw above, you can add forms to your module. This step explains how they are handled.

Take the following example:

<!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 profile="http://www.netvibes.com/api/0.3/profile">
  <title>Hello world</title>
 
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <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>
<body>
  <form method="post" action="addBookmark.php">
 
    <fieldset>
      <label for="url">URL</label><br />
        <input name="url" id="url" type="text" value=""/>
 
      <label for="title">Title</label><br />
        <input name="title" id="title" type="text" value=""/>
 
      <label for="description">Description</label><br />
        <textarea name="description" id="description" 
          cols="30" rows="5"> </textarea>
 
      <input name="add" type="submit" value="Ok"/>
    </fieldset>
  </form>
 
</body>
</html>

Test this module: http://www.netvibes.com/api/0.3/examples/example5.html

If you submit this sample form, data will be posted (the method “attribute” is set to “post”) to the “addBookmark.php” URL (defined in the “action” attribute).

Note:

Data is posted using Ajax so the page is not refreshed
“addBookmark.php” must send back data (or redirect to) a Netvibes Mini API module. The module content sent back will be simply rendered

STEP 6: Configuration forms

Let's try this special kind of form. We declare a configuration form by adding an attributed class with the value “configuration” to the form.

<!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 profile="http://www.netvibes.com/api/0.3/profile">
  <title>New configuration example</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
  <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>
<body>
 
<?php if(empty($_COOKIE['name'])) { ?>
 
<p>Module is not configured. Please edit it.</p>
 
<?php } else { ?>
 
<p><strong>Name</strong> : 
  <?php echo htmlspecialchars($_COOKIE['name']) ?></p>
 
<p><strong>Surname</strong> : 
  <?php echo htmlspecialchars($_COOKIE['surname']) ?></p>
 
<?php } ?>
 
<form class="configuration" method="post" action="">
 
  <label>Name :</label> <input name="name" type="text" value="" />
  <br />
 
  <label>Surname :</label> <input name="surname" type="text" value="" />
  <input type="submit" value="ok" />
 
</form>
 
</body>
</html>

The form is appearing in the edit section of the module instead of the body.
When you submit this form, data is not send to a URL as in 'classic forms' but instead stored in the Netvibes database.
From the moment data is stored, we make it available via the javascript getValue() function and also as HTTP Cookies.

Test this module: http://www.netvibes.com/api/0.3/examples/example6-configuration.php

Step 7: Javascript, onload binding, and Periodical Executer

In this example, we define an NV_ONLOAD function that will be automatically executed when the module load. Then, we define (with vanilla javascript or with prototype.js built-in function) that the refreshContent function will be executed each second. In the refreshContent function, we create a string with the current time, then we put in the module content using the NV_CONTENT binding and innerHTML.

<!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 profile="http://www.netvibes.com/api/0.3/profile">
 
  <title>Date and hour module</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <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>
 
  <script type="text/javascript">
  NV_ONLOAD = function() {
    // var myInterval = setInterval(refreshContent, 1 * 1000); // classic js
    var myPe = new PeriodicalExecuter(refreshContent, 1); // with prototype.js
  }
  refreshContent = function() {
    var now = new Date;
    var hour = '<strong>' + now.getHours() + ':' + now.getMinutes()
      + ':' + now.getSeconds() + '</strong>';
    NV_CONTENT.innerHTML = '<p style="text-align:center">' + hour + '</p>';
  }
  </script>
 
</head>
<body>
 <p>Loading ...</p>
</body>
</html>

Test this module: http://www.netvibes.com/api/0.3/examples/date.html

Step 8: Ajax, Proxy and RSS parsing

In this example, when the module load, we're executing an Ajax Request using the Netvibes XML proxy and prototype.js built in function. When the Ajax call is finished, we're parsing the RSS sent back using DOM, then we change the title and the content of the module by using the NV_TITLE and NV_CONTENT bindings.

<!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 profile="http://www.netvibes.com/api/0.3/profile">
 
    <title>FKDL</title>
    <script type="text/javascript">
    NV_ONLOAD = function() {
      var url = 'http://www.fkdl.com/rss.php';
      function AjaxShow(xhr) {
        // RSS Parsing
        var dom = xhr.responseXML.documentElement;
        var mainTitle = 
          dom.getElementsByTagName("title")[0].firstChild.nodeValue;
        var firstTitle = 
          dom.getElementsByTagName("title")[2].firstChild.nodeValue;
        var firstContent = 
          dom.getElementsByTagName("description")[1].firstChild.nodeValue;
 
        // Module Title
        NV_TITLE.innerHTML = mainTitle + ' : ' + firstTitle + ''; 
        // Module Content
        NV_CONTENT.innerHTML = '<div style="text-align:center">' 
          + firstContent + '</div>'; 
      }
      var request = new Ajax.Request(NV_XML_REQUEST_URL + '?url='
        + escape(url), { method: 'get', onSuccess: AjaxShow });
    }
    </script>
 
</head>
<body>
 <p>Loading ...</p>
</body>
</html>

Test this module (not exactly the same code, note the parsing issue with Safari): http://www.netvibes.com/api/0.3/examples/fkdl.html