Developers
Quick links
Subscribe
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 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:
widget.callback('onUpdateTitle');
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:
var p = UWA.$element( widget.body.getElementsByClassName("myElement")[0] ); p.setStyle("backgroundColor", "red");
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 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 Ajax examples page.
- Send to a friend
- Add to favorites
- Last modified: 2008/05/07 16:10
netvibes