======UWA one-page documentation====== UWA is the Universal Widget API, an XHTML format and JavaScript framework conceived by Netvibes in order to build highly portable widgets, both for Web and desktop platforms. The present document aims at providing as much information about UWA as possible in a single page. More detailed information, along with tutorials and examples, can be found on the [[http://dev.netvibes.com/doc/|UWA documentation site]]. For any question, check the extensive documentation or visit the Netvibes [[http://dev.netvibes.com/forum/|Developers forum]]. =====Testing a UWA widget===== A UWA widget can be tested locally, with the proper UWA look-and-feel, if its code features the two JavaScript and CSS files (see below). This Standalone mode however has its limitations. A more definitive test can and should be done by putting the file online, and using Netvibes' [[http://www.netvibes.com/subscribe.php?module=UWA|UWA module]], available in Netvibes.com Essential Widget category ; the widget can also be directly added to Netvibes by clicking the Add To Netvibes button found below the widget container when in Standalone mode. iGoogle testing can be done by displaying the online file and clicking the Add To iGoogle button found below the Add To Netvibes button when in Standalone mode. Apple Dashboard testing can be done by downloading and installing the [[http://dev.netvibes.com/files/UWA-Widget.wdgt.zip|UWA Dashboard widget]]. Opera testing can be done by downloading and installing the [[http://dev.netvibes.com/files/opera/UWA-Opera.zip|UWA Opera widget]]. Currently, no testing widget is available for the other supported platforms. =====Installing a UWA widget on widget platforms===== Once the widget is added to Netvibes Ecosystem, any user can choose to install on one of the supported Web platform (Netvibes, iGoogle, Live.com, iPhone...), download it on one of the supported desktop platforms (Vista, Apple Dashboard, Opera...). To submit a widget to Ecosystem, visit http://eco.netvibes.com/submit =====Description of a UWA file===== A UWA widget basically uses well-known Web standards, such as XHTML, JavaScript and CSS, with a specific XML format for preference portability. ====Things to remember==== * File MUST be encoded using UTF-8. * File MUST be well-formed XML. * File MUST include the Netvibes namespace. * File MUST include a tag, even empty. * File MUST NOT call external JavaScript or CSS files. * File SHOULD be static XHTML (.html, .xml), with content being updated using Ajax requests and DOM methods. ====File header: start of the file==== * A widget SHOULD begin with the following code. * Meta informations, file title and favicon MUST be adapted to each widget. * A widget SHOULD at least present an "author" meta tag. * All meta tags are optional - although it's better if they are all correctly defined. * The file SHOULD include the JavaScript and CSS emulation files, for basic standalone testing. The following sample code is informative - do not use as-is, do adapt it to your needs. Title of the Widget ====File header: preferences==== UWA preferences are encoded using a specific XML format. This makes it impossible to validate the XHTML code for now, because the XML is not standard. However, XML well-formedness is more important than XHTML validity, so such a validator should only be used for XHTML tags outside of the '''' ones. * Preferences MUST use the [[:uwa_specification:content_of_the_xhtml_file#preferences|described options]]. * Preferences values MUST NOT contain HTML entities (i.e. "é"), they MUST rely on UTF-8 and use real characters instead ("é") - this in order not to break the XML parsing. The following sample code is informative, listing all available types of preferences - do not use as-is, do adapt it to your needs. * A widget that does not need preferences SHOULD at least contain an empty preferences tag. * Preferences MUST be called from JavaScript using one of these methods: - ''var myVar = widget.getValue(prefName);'' - ''var myBool = widget.getBool(booleanPref);'' - ''var myNumber = widget.getInt(integerPref);'' * Preferences can be set/modified through JavaScript (except for the ''range'' and ''list'' types), using a single method: - ''widget.setValue(prefName, newValue);'' ====File header: CSS tag==== * The CSS enclosing tag MUST be valid XHTML. * If no CSS is necessary, the Note that the above code uses a potentially unusual way of writing JavaScript code: functions are declared as anonymous, and variables are contained within a JavaScript object (hereby named ''YourWidgetName''). While this coding style is generally recommended to improve readability and lessen the risk of name collision, you can use the coding style you prefer. =====JavaScript: The widget & UWA objects===== UWA both extends and limits JavaScript, in order to offer more tools to developers, and to ensure that widgets do not interfere with each other. * The ''document'' and ''window'' MUST NOT be used. Most of their method are available through the ''widget'' object. For more documentation and usage information, check the documentation and examples available at http://dev.netvibes.com/doc/ ====JavaScript: widget methods==== ===Widget methods=== ''widget.setAutoRefresh()'' sets the refreshing value - overrides the ''autoRefresh'' meta. delay is expressed in minutes ''widget.setSearchResultCount()'' updates the widget's title with a result count, if greater or equal to zero ''widget.setTitle()'' sets the title of the widget - overrides the file's '''' value ''widget.setUnreadCount()'' updates the title with an unread count, if greater or equal to zero ===Platform methods=== ''widget.addStar()'' Netvibes only - triggers Netvibes starring system, in order to add a favorite to the logged user's timeline. ''widget.log()'' 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()'' opens a new browser window with the given URL ===DOM methods=== ''widget.body'' returns a reference to the XHTML body content (equivalent to ''document.body'', but limited to the widget) ''widget.createElement()'' create a new DOM element ''widget.setBody()'' sets the body of the widget. Argument must be valid XHTML code. The previous content of the body is erased and replaced by the value of the first argument. ===Widget preferences methods=== ''widget.getValue()'' retrieves the value of the given preference name. Returns a string. ''widget.getInt()'' retrieves the value of the given preference name. Returns an integer. ''widget.getbool()'' retrieves the value of the given preference name. Returns a boolean value (true/false). ''widget.setValue()'' sets name with the value value ====JavaScript: widget properties==== ''widget.lang'' returns the user's language/dialect, depending on his platform settings (default: en_US) ''widget.locale'' returns the user's locale, depending on his platform settings (default: us) ''widget.readOnly'' Netvibes only - returns true if the widget is display within a Netvibes Universe, false otherwise. Used to make sure no code allowing to send data to a private account is displayed. ====JavaScript: widget events==== The following events should be declared only once, by assigning a function or block of code to them. ''widget.onLoad()'' triggered when the widget is launched - MUST be declared in order for the whole JavaScript code to be lanched ''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 ===JavaScript: callback events=== To be called with ''widget.callback()'' (for instance, ''widget.callback('onUpdateBody');''). ''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() ====JavaScript: UWA methods==== ''UWA.$element()'' Extends hand-created XHTML elements with UWA's element extensions (see below). ===UWA.Data methods (Ajax methods)=== Full documentation for these Ajax methods is available at http://dev.netvibes.com/doc/ ''UWA.Data.getFeed(url, callback)'' gets the content of a feed, in the internal JSON Feed format. ''UWA.Data.geJson(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.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.request(url, request object)'' this is the master data request method, of which the getXml(), getJson() and getText() are shortcuts to. =====JavaScript: element extensions===== For a given reference 'el' to an XHTML element. ===Modifying the element's content=== ''el.addContent()'' adds content in a div at the end of the element's existing content ''el.appendText()'' adds a new text node at the end of the element's existing content ''el.empty()'' empties the element (equivalent to: el.innerHTML = "") ''el.setText()'' sets a text node in the element el.setHTML() sets the HTML content of the element (el.innerHTML equivalent) ''el.setContent()'' empties the element, then fills it with content ''el.setStyle()'' sets the property CSS property, with the value value ===Getting the element's DOM info=== ''el.getDimensions()'' returns a JSON object with 2 properties: width and height, each relating to the element's widht and height ''el.getElementsByClassName()'' returns all the elements that are associated with the given CSS class name ''el.getElementsByTagName()'' returns an array of elements corresponding to the given tag name ''el.getParent()'' return a collection of the element's parent node ''el.getChildren()'' return a collection of the element's child nodes ===Modifying the element's display=== ''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 ===Modifying the element's classes=== ''el.hasClassName()'' returns true if the element has the given class name as one of its class names ''el.addClassName()'' adds the given class name to the element's existing class names ''el.removeClassName()'' removes the given class name from the element's existing class names