====== 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 "[[:uwa_specification:using_javascript_and_ajax#the_widget_object|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.

===== widget.onLoad =====

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!

<code javascript>
// 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();
  }
</code>


===== widget.onRefresh =====

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:

<code javascript>
widget.onRefresh = widget.onLoad;
</code>

There is a clever way to use it: 
  - 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).
  - 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:

<code javascript>
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;
</code>

<note tip>
Preferences with an [[:uwa_specification:content_of_the_xhtml_file#preference_attributes|''onchange'' attribute]] are not affected by this event, and do not affect it. Their attribute only triggers the specified method.

Of course, you could set the attribute as ''onchange="onRefresh"'', in which case the specified method would indeed be ''widget.onRefresh''...
</note>


===== widget.onResize =====

<note tip>
The event described herein only work within Netvibes at the moment.
</note>

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 [[:examples:apod|Astronomy Picture of the Day widget]], we find this code:

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


===== widget.onKeyboardAction =====

<note tip>
The event described herein only work within Netvibes at the moment.
</note>

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.

<code javascript>
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)
    }
</code>

Here are some other potentially useful keycodes:

^  Keycode     ^  Key                          ^
|  8           |  Backspace                    |
|  9           |  Tab                          |
|  13          |  Enter                        |
|  46          |  Delete                       |
|  96 to 105   |  0 to 9 on the numerical pad  |
|  112 to 123  |  F1 to F12 keys               |


===== widget.onSearch =====

<note tip>
The events described herein only work within Netvibes at the moment.
</note>

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:
  - the first one is the query itself, a string containing the text your user is looking for. We call it ''query''.
  - 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.



==== widget.onResetSearch ====

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.

<note tip>
You can see a working example of the usage of these two events, and the code the it implies, in the [[:examples:rssreader|RSS Reader sample widget]].
</note>