Using events in UWA

The widget object provides a handful of events to handle the interactivity of your widget: you can easily build useful methods to respond to specific events from the widget itself, or the user activity. Those events are listed on the ”Using JavaScript and Ajax” section.

The purpose of this page is not to list all available events, but to give examples of their use. As for any JavaScript events, the UWA events are handlers to which you assign methods. Once the event is triggered, the method is called.

Might be the most important event - at least, it needs to be in your widget if intend to have clean code.

This event occurs immediately after the widget is fully loaded. It should therefore contain (or point to) the lines of code to be executed. It is basically a replacement for the onload event - which must not be used!

// contains the code.
widget.onLoad = function() {
  // my init code
  }
 
// points to some code.
// cleaner if you use a lot of code.
widget.onLoad = NameOfTheWidget.myInitCode;
// which is the same as
widget.onLoad = function() {
  NameOfTheWidget.myInitCode();
  }

This event handler is triggered when one of the following events occur:

• the Edit section is closed (by clicking on Edit or on the OK button)
• when a preference with an onrefresh attribute is changed
• the Refresh button is clicked (icon on the top-bar of the widget)
• when the autoRefresh meta value ends (this meta will even only work if widget.onRefresh is set)

You can tell the widget to reload itself entirely on refreshing by using this code:

widget.onRefresh = widget.onLoad;

There is a clever way to use it:

1. make widget.onLoad point to an initialization function A, which for instance loads the data through Ajax, and in turn points to a function B that processes the loaded data (i.e, displays the data according to the preferences).
2. make widget.onRefresh point to the processing method B. This way, the widget doesn't have to initialize anything again on refresh, and just changes the display using the already loaded data, according to the modified preferences.

For instance:

var NameOfTheWidget = {};
 
NameOfTheWidget.myInitCode = function() {
  // do your data loading here, for instance:
  UWA.Data.getXml(
    'http://example.org/api.php', 
    NameOfTheWidget.myDataProcessor 
    );
  }
 
NameOfTheWidget.myDataProcessor = function(response) {
  // do your data processing/displaying here
  }
 
widget.onLoad = NameOfTheWidget.myInitCode;
widget.onRefresh = NameOfTheWidget.myDataProcessor;

This event is triggered when the widget dimensions has changed, which one of this has happened:

• the browser has been resized
• the Netvibes columns have been resized
• the Netvibes sidebar has been opened/closed

It allows your widget to adapt its content's size (mostly the width) according to its new dimension.

Useful method in this case is widget.body.getDimensions(). For instance, in the Astronomy Picture of the Day widget, we find this code:

widget.onResize = function() {
  var elements = widget.body.getElementsByTagName("img");
  var image = elements[0];
  if (image) {
    image.width = 1;
    image.width = widget.body.getDimensions().width;
    }
  }

This handler gives the registered method's first argument the keycode to act upon. You can then use this keycode to interpret the instructions from the user.

Please be aware that while custom key events can be useful, your browser, system and even Netvibes may use their own key events and combination. Try not to disable useful keys events in the process of creating your own.

widget.onKeyboardAction = function(keyCode) {
  if (keyCode == 72 || keyCode == 112) {
    // if the user presses 'h' or 'F1'
    // example use: display the 'help' info for your widget
    } 
  else if (keyCode == 32) {
    // user presses the Space key
    // example use: jump to the next item
    }
  else if (keyCode == 27) {
    // user presses the Escape key
    }
  else if (keyCode >= 49 && keyCode <= 57) {
    // user presses a numerical character (between '0' and '9')
    }
  else if (keyCode >= 65 && keyCode <= 90) {
    // user presses an alphabetical character (between 'a' and 'z')
    }
  else if (keyCode >= 37 && keyCode <= 40) {
    // user presses an arrow character (37=left, 38=up, 39=right, 40=down)
    }

Here are some other potentially useful keycodes:

This event is triggered when a search is done within Netvibes itself (with the search-box on top of the interface). The search goes through all your tabs and widgets to find ones which match your user's query.

Setting up this event therefore allows your widget to take work with Netvibes searches - if not, you widget would just retract itself during a search, to leave more space to widgets that do support it.

The idea of this event is to pass the search query to your widget, and let your widget make launch that search query on the data it has access to, and return only the results, or to highlight them in the current data set, depending on the type of search.

widget.onSearch takes two parameters:

1. the first one is the query itself, a string containing the text your user is looking for. We call it query.
2. the second one is a boolean value (true or false), which indicates if the query should be used as a search (true), or as a filter (false).
   • If true, query is applied to all the widgets on the tab (YouTube search, Flickr search, eBay search… all at the same time).
   • In false, query filters the displayed content of the widgets to only display the items containing query.

The second case (false) is the default behavior for the Netvibes search, but you can make use of the first case thanks to that second parameter.

This events is triggered when the user cancels his search in the Netvibes search-box (by click the X icon). It allows your widget to get back to a normal display. It is therefore only useful if you already implement widget.onSearch: you can rest anything that pertains to search/filtering.