======Using JavaScript and Ajax in a UWA widget======

The UWA provides a customized environment, with some restrictions and banned keywords. The API provides, among others, the ''widget'' object as an alternative to common JS objects like ''document'' and ''window''.

Please note that widgets may now be executed in an IFRAME. We strongly advise you to include this case in your tests.

=====The widget object=====
Since UWA widgets are entirely built using JavaScript on static XHTML files, the API provides the developer with many events and methods, encapsulated in JavaScript objects, the most important one being the ''widget'' object, an instance of the UWA ''Widget'' class. 

The ''widget'' object replaces the ''document'' DOM object. Most of its events and methods are alternatives to their JavaScript/DOM counterparts, which in the restricted environment are unavailable or limited.

Since the ''Widget'' class is automatically instantiated by the Netvibes environment (or the emulation profile, in the case of standalone widgets), the ''widget'' object and its events and methods are directly accessible throughout your widget's JavaScript code.

====Events====
The ''widget'' object handles the following events:
^  Event name                ^  Description                            ^
|  ''widget.onLoad''         |  triggered when the widget is launched  |
|  ''widget.onRefresh''      |  triggered when the widget is refreshed (manually or automatically)  |
|  ''widget.onResize''       |  triggered when the widget is resized  |
|  ''widget.onSearch''       |  triggered when a search is performed within Netvibes.  |
|  ''widget.onResetSearch''  |  triggered when the search is reset in Netvibes  |
|  ''widget.onKeyboardAction''  |  triggered when a key is pressed. You can associate specific keys to specific methods  |

Check the [[:howto:use_events|events use]] howto for the proper usage of some of them.

===Callback events===
These methods are triggered by specific ''widget'' methods, but are also available for your own code.
^  Event name         ^  Description  ^
|  ''onUpdateTitle''  |  triggered when the widget's title is modified. Used by ''widget.setTitle()''  |
|  ''onUpdateBody''   |  triggered when the widget's content is set or updated. Used by ''widget.setBody()'' and ''widget.addBody()''  |

Those can be triggered this way:

<code javascript>
widget.callback('onUpdateTitle');
</code>

====Methods====

The ''widget'' object provides the following methods:

^  Method name                       ^  Description  ^
|  ''widget.addBody(content)''       |  adds content to the end of the existing body. If the content is of type ''string'', ''addBody'' encapsulates it in a ''div'' before adding it all to the body  |
|  ''widget.createElement(tagName)''  |  create a new DOM element  |
|  ''widget.getValue(name)''         |  gets the value set in ''name''  |
|  ''widget.log(string)''            |  logs ''string'' in the JavaScript console (provided the browser supports it, i.e. with Firebug, and that ''debugMode'' is set to ''true'' in the file's meta tags)  | 
|  ''widget.openURL(url)''           |  opens a new browser window with the given URL  |
|  ''widget.setAutoRefresh(delay)''  |  sets ''autoRefresh'' meta value. ''delay'' is expressed in minutes  |
|  ''widget.setBody(content)''       |  sets the body of the widget. ''content'' must be valid XHTML code. The previous content of the body is erased and replaced by ''content''  |
|  ''widget.setSearchResultCount(count)''  |  updates the widget's title with the result count, if greater or equal to zero  |
|  ''widget.setTitle(title)''        |  sets the title of the widget  |
|  ''widget.setUnreadCount(count)''  |  updates the title with the unread count, if greater or equal to zero  |
|  ''widget.setValue(name, value)''  |  sets ''name'' with the ''value'' value  |

Please note that events and methods must be called using their full reference: use ''widget.onLoad'', not just ''onLoad'' or any other way.

=====Properties=====

The ''widget'' object provides the following properties:

^  Property name        ^  Description  ^
|  ''widget.body''    |  returns a reference to the XHTML body content  |
|  ''widget.lang''    |  returns the user's language/dialect (default: ''en_US'')  |
|  ''widget.locale''  |  returns the user's locale (default: ''us'')  | 

=====Element extensions=====

The following methods are available to all HTML elements within the widget content (''el'' is any applicable element, even ''widget.body''). 

^  Style and content extensions                         ^^
|  ''el.addContent(content)''  |  adds ''content'' in a ''div'' at the end of the element's existing content  |
|  ''el.appendText(text)''       |  adds a new text node at the end of the element's  existing content  | 
|  ''el.empty()''  |  empties the element. (''el.innerHTML = ""'' equivalent)  |
|  ''el.getDimensions()''  |  returns a JSON object with 2 properties: ''width'' and ''height'', each relating to the element's widht and height  |
|  ''el.getElementsByTagName(tagName)''  |  returns an array of elements corresponding to the given tag name  |
|  ''el.getParent()''  |  return a reference to the element's parent node  |
|  ''el.getChildren()''  |  return a collection of the element's child nodes  | 
|  ''el.setText(text)''        |  sets a text node in the element  |
|  ''el.setHTML(html)''        |  sets the HTML content of the element (''el.innerHTML'' equivalent)  |
|  ''el.setContent(content)''  |  empties the element, then fills it with ''content''  |
|  ''el.setStyle(property, value)''  |  sets the ''property'' CSS property, with the ''value'' value  |

^  Display related extensions  ^^
|  ''el.hide()''  |  sets the element's ''display'' CSS rule to ''none''  |
|  ''el.show()''  |  empties the element's ''display'' CSS rule  |
|  ''el.toggle()''  |  toggles the element's ''visible'' CSS rule between ''hide'' and ''show''  |
|  ''el.remove()''  |  removes the element from the DOM tree  |

^  Class related extensions  ^^
|  ''el.getElementsByClassName(className)''  |  returns all the elements that are associated with the given CSS class name  |
|  ''el.hasClassName(className)''  |  returns ''true'' if the element has the given class name as one of its class names  |
|  ''el.addClassName(className)''  |  adds the given class name to the element's existing class names  |
|  ''el.removeClassName(className)''  |  removes the given class name from the element's existing class names  |

====Extending elements====

These extensions are currently only automatic for ''widget.body'' and elements created through ''widget.createElement''. For other elements, you can extend them use the ''UWA.$element'' method:

<code javascript>
var p = UWA.$element( widget.body.getElementsByClassName("myElement")[0] );
p.setStyle("backgroundColor", "red");
</code>

=====Ajax=====

Ajax is now a central part of widget development, and the UWA therefore provides the needed tools through the UWA.Data object.

In all ''UWA.Data'' methods, the expected ''responseText''/''responseXML'' return value is automatically passed as a first argument of the given callback method.

^  Method name  ^  Description  ^
|  ''UWA.Data.getFeed(url, callback)''  |  gets the content of a feed, in [[:uwa_specification:uwa_json_feed_format|our JSON format]]  |
|  ''UWA.Data.getXml(url, callback)''  |  gets the content of an external XML data source. It can be used to retrieve the content of a feed in XML format  |
|  ''UWA.Data.getJson(url, callback)''  |  gets the content of an external data source, in JSON format. The JSON format is the one from the API you call, not the same as the one obtained through ''UWA.Data.getFeed()''  |
|  ''UWA.Data.getText(url, callback)''  |  gets the content of an external XML data source, in plain text format  |
|  ''UWA.Data.request(url, request)''  |  this is the master data request method, of which the ''getXml()'', ''getJson()'' and ''getText()'' are shortcuts to  |

To see examples of their use, and to decide which to use according to your data and service, you should read the [[uwa_specification:ajax_examples|Ajax examples]] page.