Back to my page

Developers

You are here: Home » Netvibes Mini-Module API » Netvibes mini API Documentation
Table of Contents

Netvibes mini API Documentation

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: 04/07/2006

Netvibes mini API is a way to create your own Netvibes modules. Netvibes mini API Modules are in fact simple HTML pages that you host on your web server like any others. The modules can be complex, with multiple pages, forms and scripting server side (with PHP, for example). The philosophy behind the Mini Module API is to be as simple as possible, in a spirit close to Microformats.

Netvibes mini API Modules must not only work within Netvibes but may also be fully functional and testable in standalone mode.

Format

  • Netvibes mini API Modules SHOULD be valid XHTML pages
  • Netvibes mini API Modules MUST be XML well formed
  • Netvibes mini API Modules MUST be utf-8 encoded
  • Netvibes mini API Modules SHOULD declare the HTML profile of the spec used in the HTML header 
 <head profile="http://www.netvibes.com/api/0.3/profile">

The XHTML validity is very important because Modules are rendered through the browser XML parser, so they MUST be well formed XML.

Title

The Title of the module is contained in the TITLE element in the HEAD section of the HTML document. 

 <head>
 <title>My first Netvibes module</title>
 </head>

Content

The Content of the module is contained in the BODY section of the HTML document 

 <body>
  <p>My first paragraph within a Netvibes module.</p>
 </body>

Favicon

If the document contain in the HEAD section a LINK element with a REL attribute equal to “icon” , Netvibes will display a favicon for the module located at the HREF attribute value of the LINK element. 

 <link rel="icon" type="image/png" href="http://www.example.com/favicon.png" />

HyperLinks

  • If the URI defined in the link's href attribute is relative, Netvibes will look for a module located at the URI
  • If the URI defined in the link's href attribute is absolute, Netvibes will open a new window

CSS

  • Inline CSS are supported
  • Internal CSS are supported
  • External CSS are not supported today

Javascript

  • External Javascript scripts (with an src attribute) are not supported today
  • Internal Javascript scripts (without an src attribute) are executed when the Module loads

Bindings

  • NV_ONLOAD: is a function that will be called when the module loads
  • NV_TITLE: is the html element containing the module title
  • NV_CONTENT: is the html element containing the module content 
 NV_ONLOAD = function()
 {
   alert('The module is loaded');
   NV_TITLE.innerHTML = 'New title';
   NV_CONTENT.innerHTML = '<p>New content</p>';
 }
<code>
 
  * ''NV_KB_ENTER'': is a function that will be call when user press enter into the module
  * ''NV_KB_ACTION'': is a function that will be call when user press other keys 
 
<code javascript>
 NV_KB_ENTER = function() {
   alert('You pressed enter');
 }
 NV_KB_ACTION = function(keyCode) {
   alert('You pressed #' + keyCode);
 }
  • NV_REFRESH: is the function to refresh. You can call it and you can override it too. 
 // Mapping refresh on the R key
 NV_KB_ACTION = function(keyCode) {
   if(keyCode == '82') NV_REFRESH()
 }
 
 // Defining our own refresh function
 NV_REFRESH = function() {
   alert('You refreshed the module');
 }

Functions

  • saveValue(name, value): store the value of the variable name on the Netvibes server
  • getValue(name): get the value of the variable name from the Netvibes server 
 saveValue('author', 'Tim Berners Lee');
 var author= getValue('author');
  • setToolTip(element, text, width): create a Tooltip on an element 
 var a = NV_CONTENT.getElementsByTagName('a')[0];
 a.onmouseover = function() {
   setToolTip(this, 'This is a Tooltip');
 }

Notes on Javascript handling

  • Use of document.getElementById and prototype.js $() function is discouraged, it can be problematic when the same module is loaded more than once. You have to use relative reference to select an object in the DOM.
  • Use of inline events attributes (onclick, onmouseover, …) is discouraged, in fact you can't access to your module function and properties this way. You have to define this behaviours dynamically. 
 // example with getElementsByClassName()
 var elements = document.getElementsByClassName('items', NV_CONTENT)[0];
 // or // example with getElementsByTagName()
 var links = NV_CONTENT.getElementsByTagName('a');
 links[0].onclick = function() { alert('Click'); }

Forms

When a form is submitted, an Ajax call is executed to the URL defined in the action attribute using the HTTP method (GET or POST) defined in the method attribute. Form data is sent in the body request as expected, using the x-www-form-urlencoded Content-Type.

The content sent back by the script SHOULD be an HTML document describing a Netvibes Mini API Module. When the Ajax call is complete, the content sent back is simply rendered.

Configuration forms

If a form has a class attribute with a value of “configuration” the behaviour is different, it become a “configuration form”. The configuration form is not displayed in the module body but appear in the module edition zone (when you click “edit” in the module header).

When a configuration form is submitted, data contained in the form are stored on the Netvibes server. From the moment they are stored, they are automatically accessible via the getValue() function and also available as HTTP Cookies in the next request to your Netvibes Mini API modules. The variable name used is equal to the form element name attribute. 

 <form class="configuration" method="post" action="">
 <fieldset>
 <label for="limit">Number of items to display :</label>
 
 <select id="limit" name="limit">
 <option value="1">1</option>
 <option value="2">2</option>
 
 <option value="3">3</option>
 </select>
 <input type="submit" value="ok" />
 
 </fieldset>
 </form>

HTTP Headers

  • Accept-Language: we currently fill the Accept-Language header with the lang choose by the Netvibes user.

Proxies

Because browsers restrictions (Same Origin Policy), you have to use proxies to communicate through Ajax calls with external data sources. There are two proxies available on Netvibes server:

  • NV_XML_REQUEST_URL (xmlProxy.php) is the proxy we recommend to handle RSS. It does have a 20 minutes caching
  • NV_AJAX_REQUEST_URL (ajaxProxy.php) is the proxy we recommend for other Ajax Request. It does relay the HTTP POST datas.

To use the proxy, just pass to it an url argument containing the URL you want to locate. You can use the browser built-in XMLHttpRequest method or use Ajax.Request from prototype.js. 

var url = 'http://www.example.com/blog/rss.php';
var request = new Ajax.Request(
  NV_XML_REQUEST_URL + '?url=' + escape(url),
    { method: 'get', onSuccess: myCallBackFunction }
  );
  function myCallBackFunction(xhr) {
    // your code
  }

Business

Partner with us.

Developers

Build once, run everywhere.

Community

Get involved, get localized.

Press

News. Media kits. Press releases.