====== UWA JavaScript Framework ======


UWA provides an advanced programming experience through its JavaScript framework.

<note>Widgets are executed within an IFRAME. We strongly advise developers to include this case in their tests.</note>

===== The widget object =====

The JS framework 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  |


=== 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 events are triggered internally. If needed, they can be triggered manually. For instance, in order to have the widget adapt its size to its content, this line should be added at the end of the DOM-updating code:

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

==== Methods ====

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

=== Widget preferences methods ===

^  Method name                       ^  Description  ^
|  ''widget.getValue(name)''         | Retrieves the value set in ''name'' preference. Returns a string  |
|  ''widget.getInt(name)''              | Retrieves the value set in ''name'' preference. Returns an integer  |
|  ''widget.getBool(name)''           | Retrieves the value set in ''name'' preference. Returns a boolean (true/false) |
|  ''widget.setValue(name, value)''  | Sets the ''name'' preference with the ''value'' value  |


=== Widget methods ===

^  Method name                       ^  Description  ^
|  ''widget.setAutoRefresh(delay)''  | Sets ''autoRefresh'' meta value. ''delay'' is expressed in minutes  |
|  ''widget.setSearchResultCount(count)''  | Updates the widget's title with a result count, if greater or equal to zero  |
|  ''widget.setTitle(title)''        | Sets the title of the widget (overrides the one set in the ''title'' tag)  |
|  ''widget.setUnreadCount(count)''  | Updates the title with an unread count, if greater or equal to zero  |


=== DOM methods ===

^  Method name                       ^  Description  ^
|  ''widget.addBody(content)''       | Adds ''content'' to the end of the existing ''body'' tag. If the content is of type ''string'', ''addBody'' encapsulates it in a ''div'' before adding it all to the ''body'' tag  |
|  ''widget.createElement(tagName, options)''  | Creates a new DOM element  according to the provided "tagName". See below for details.  |
|  ''widget.setBody(content)''       | Replaces the content of the widget's ''body'' tag with ''content''. ''content'' must be valid XHTML code.  |

== createElement ==

''createElement'' 's ''options'' parameter can greatly shortern your element-creating code:
  - if ''options'' is not defined, it works just like document.createElement(tagName) ;
  - if options is defined, its works like JS frameworks DOM builders: ''new Element(tagName, options)''. ''options'' takes the form of a JSON-like object

Examples:
<code javascript>
var div = widget.createElement('div');

var input = widget.createElement( 'input', 
  { 'type': 'submit', 'value': 'Update' } );
</code>


=== Other methods ===

^  Method name                       ^  Description  ^
|  ''widget.addStar(json)''  | Triggers Netvibes' starring system, in order to add a favorite link to the logged user's timeline. In-Netvibes use only  |
|  ''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  |

<note>''widget.addStar()'''s argument must take the form of a JSON object: ''{'title':'xxx','url':'http://yyy'}''.</note>

=====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'')  | 
|  ''widget.readOnly''  | Returns ''false'' if the widget's preferences can be modified (private page), ''true'' otherwise (public page). In-Netvibes use only  |


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

The following methods are available to HTML elements that are UWA-extended, within the widget ''body'' tag. Elements are automatically UWA-extended when they are created using ''widget.createelement()''. The ''body'' tag is extended by default.

<note tip>Other elements can be manually extended by using the ''UWA.extendElement()'' method:

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

''UWA.extendElement()'' deprecates the former ''UWA.$element()''.
</note>

In the following tables, ''el'' is any applicable element (including ''widget.body''). 

^  Style and content extensions                         ^^
|  ''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()''  | Returns a reference to the element's parent node  |
|  ''el.getChildren()''  | Returns 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.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  |

=====Ajax=====

Ajax is a central part of UWA widget development. UWA developers should rely on the ''UWA.Data'' object for data requests.

All of ''UWA.Data'''s methods pass the Ajax request's ''responseText''/''responseXML'' value as a first argument of the given callback method.

^  Method name  ^  Description  ^
|  ''UWA.Data.getFeed(url, callback)''  | Gets the content of a feed, and returns it as a JSON object, in JSON Feed format  |
|  ''UWA.Data.getXml(url, callback)''  | Gets the content of an external XML data source and returns an XML object - which can be parsed using the platforms's XML-specific methods, such as ''el.childNodes'' or ''el.firstChild''. It can also 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 a external data source, in plain text format  |
|  ''UWA.Data.request(url, request)''  | The master data request method, upon which the other methods are based  |