Universal Web App

Universal Web App (UWA)

Latest Version: 1.3RC4

Editors:

Copyright 2006-2012 Netvibes, a Dassault Systèmes company. All rights reserved.

Abstract

This document describes the Universal Web App (UWA), a combination of an XHTML-based file format and a JavaScript framework.

Its goal is to allow developers to use existing web standards to build web applications. Support for these applications should be easy to implement on any platform that already supports the usual web standards: XHTML, CSS and JavaScript.

Transcompilers (also known as transpilers or compilers) might be required to turn the application (notably its XML format for preferences) into the native platform's own model.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current Netvibes publications and the latest revision of this technical report can be found in the Netvibes developper website at https://dev.netvibes.com

This is a work in progress and may change without any notice.

Please send comments to uwa@netvibes.com with [UWA] at the start of the subject line.

This document is produced by the Netvibes Company. Publication as a Working Draft does not imply endorsement by the Netvibes Company. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

Introduction

The Universal Web App (UWA) is a application format that aims to be easy to use for web developers, easy to implement for platform developers and as portable as possible.

To that end, it is based on well-known web technologies, such as XHTML for content, XML for preferences handling, JavaScript for behavior and CSS for styling.

It has been designed from the get-go so that web developers can build a working application in a matter of minutes, and that platform implementers can quickly have it working for their platform.

In the context of this specification, an application is defined as a piece of code residing on a web server that can be embedded into a container prior to being served to the client. That container can either be embedded within a website (for instance, an online app engine or a simple web page), or exported as single-file archive, compatible with a desktop app engines.

For this purpose, this specification defines:

These three elements are expected to work within the constrains of usual web-development: they are no different to the usual formats used every day to produce a regular website.

Terminology

The term "DOM" is used to refer to the API set made available to scripts in web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core specifications.

The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.

Example of an Application

This section is non-normative, but is functional. Its purpose is to get a view of a typical source for a application.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
  xmlns:widget="http://www.netvibes.com/ns/">

  <head>

    <!-- Application Title -->
    <title>Latest blog post</title>

    <!-- Application Metas -->
    <meta name="author" content="John Doe" />
    <meta name="email" content="john.doe@example.com" />
    <meta name="website" content="http://example.com" />
    <meta name="description" content="Displays latest post from a feed" />
    <meta name="version" content="1.0" />
    <meta name="apiVersion" content="1.3" />
    <meta name="debugMode" content="false" />
    <meta name="strictMode" content="false" />

    <!-- Application thumbnail and screenshot -->
    <meta name="thumbnail" content="http://www.example.com/app-logo.png" />
    <meta name="screenshot" content="http://www.example.com/app-full.png" />

    <!-- Application Icons -->
    <link rel="icon" type="image/x-icon" href="http://www.example.com/app/favicon.ico" />
    <link rel="icon" type="image/png" href="http://www.example.com/app/favicon.png" />
    <link rel="rich-icon" type="image/png" href="http://www.example.com/app/richicon.png" />

    <!-- Application Standalone emulation files -->
    <link rel="stylesheet" type="text/css" href="//cdn.uwa.netvibes.com/lib/c/UWA/assets/css/standalone.css"/>
    <script type="text/javascript" src="//uwa.netvibes.com/lib/c/UWA/js/UWA_Standalone_Alone.js"></script>

    <!-- Application Preferences -->
    <widget:preferences>
        <widget:preference type="text" name="feedUrl" label="RSS/Atom feed to use" defaultValue="https://blog.netvibes.com/rss.php"></widget:preference>
    </widget:preferences>

    <!-- Application JavaScript Source -->
    <script type="text/javascript">
    //<![CDATA[

      var DisplayLatestBlogPost = {

          load: function () {
              UWA.Data.getFeed(widget.getValue('feedUrl'), DisplayLatestBlogPost.display);
          },

          /*
              Method: display

                Handle response from UWA.Data.getFeed in order to display
                first feed item from preference feedUrl
          */
          display: function(feed) {

              var latestPost = feed.items[0];

              // Set Application title
              widget.setTitle('<a href="' + feed.link + '">' + feed.title + '</a>');
              widget.setIcon(feed.link, true);

              // Set Application content

              // Syntax using UWA JS Runtime 1.3+ version
              widget.body.setContent([
                  {
                      tag: 'h2',
                      html: {
                          tag: 'a',
                          href: latestPost.link,
                          html: latestPost.title
                      }
                  },
                  {
                      tag: 'p',
                      text: 'Posted on ' + latestPost.date
                  },
                  {
                      tag: 'div',
                      html: latestPost.content
                  },
                  {
                      tag: 'p',
                      html: [
                          'Read all the previous posts by ',
                          {
                              tag: 'a',
                              href: feed.link,
                              text: 'visiting the blog'
                          },
                          '!'
                      ]
                  }
              ]);

              // Syntax using UWA JS Runtime 1.2 version
              /*
              var contentHtml = '';
              contentHtml += '<h2><a href="' + latestPost.link + '">' + latestPost.title + '</a></h2>';
              contentHtml += '<p>Posted on ' + latestPost.date + '<p/>';
              contentHtml += latestPost.content;
              contentHtml += '<em>Read all the previous posts by <a href="' + feed.htmlUrl + '">visiting the blog</a>!</em>'
              widget.setBody(contentHtml);
              */
          }
      };

      // Syntax using UWA JS Runtime 1.3+ version

      // Simple event setter
      /* widget.addEvent('onLoad', DisplayLatestBlogPost.load); */

      // Or using multiple events setter
      widget.addEvents({
          onLoad: DisplayLatestBlogPost.load,
          onRefresh: DisplayLatestBlogPost.load
      });

      // Syntax using UWA JS Runtime 1.2 version
      /* widget.onLoad = DisplayLatestBlogPost.load; */

    //]]>
    </script>
  </head>
  <body>
    <!-- Application XHTML Source -->
    <p>Your Feed is loading...</p>
  </body>
</html>

File format and Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.

UWA is an application format based entirely on XHTML, CSS, and JavaScript, upon which two additions are made:

Apart from these specifics, the file-format stays the same as any other well-formed XHTML web page.

A valid UWA application file follows the following rules:

The XML well-formedness is very important, as applications are rendered through an XML parser. Without it, rendering the application would be impossible, as would be compilation for other platforms. As a debugging facility, it is advised for implementers to display an error message instead of the application if any XML error is found.
Note that no specific DTD is used, so the XML preferences are bound to break XHTML validation. This SHOULD not impact upon the proper display of the application.

While it is recommended for an application to be based on a single static file and to rely on a remote dynamic file for data reading/sending through Ajax requests, the application developer can choose to rely solely on a dynamically-generated application based on a series of dynamic files if need be.
Implementations of UWA SHOULD take into account that the application might be dynamically generated.

Application head Metas data

UWA defines a number of specific meta tags, in order to give more information about the application, its developers, etc.
These meta tags use the same format as XHTML's standard meta tags: they use a "name" attribute for identification, and a "content" attribute for value.
If meta tags are present, a UWA implementation should make use of them to either display information to the user, or trigger internal code, depending of the meta's purpose.
All these meta tags are optional, but some are mandatory on a platform basis.

Author

Purpose: indicates the name of the developer/company responsible for the application.
Implementations can display this name to users, for instance when the preference section is opened.

Sample usage:

<meta name="author" content="John Doe from ACME Inc." />

E-mail

Purpose: indicates the e-mail address of the developer/company responsible for the application.
The value of the "content" attribute SHOULD be a valid e-mail.
Implementations could use it to generate a contact/bug report form.

Sample usage:

<meta name="email" content="john@example.com" />

Website

Purpose: indicates the URL of the developer's website.
The value of the "content" attribute SHOULD be a valid URL.
Implementations could use as a link to place on the developer's name, if present.

Sample usage:

<meta name="website" content="http://www.example.com" />

Description

Purpose: provides a description of the application.
Implementations could use within their application directory.

Sample usage:

<meta name="description" content="A descriptive description" />

Version

Purpose: indicates the version of the app.
Implementations could display the version to users, for instance when the preference section is opened.

Sample usage:

<meta name="version" content="0.7 beta 2" />

API-Version

Purpose: indicates the version of UWA JavaScript API used throughout the app.
For internal use only.

Sample usage:

<meta name="apiVersion" content="1.3" />

Auto-refresh

Purpose: indicates the number of minutes between two automatic reloads of the application, or between two triggerings of the onRefresh events if it exists.
The value of the "content" attribute MUST be a positive integer.

Sample usage:

<meta name="autoRefresh" content="20" />

Debug mode

Purpose: If true, a call to the widget.log() method SHOULD send the value of the method's first argument to the platform's local console (i.e., Firebug, console, etc.).
If false, nothing is done when the widget.log() method is called.
The value of the "content" attribute MUST be a textual boolean value: either "true" or "false".

Sample usage:

<meta name="debugMode" content="true" />

Strict mode

Purpose: if true, the application JavaScript syntax will be checked using JSLint Code Quality Tool.
The value of the "content" attribute MUST be a textual boolean value: either "true" or "false".

JsLint rules config used for JavaScript syntax checking:

version:  2012-02-03    // JsLint version
bitwise:  true          // If bitwise operators should be allowed
continue: true          // If the continuation statement should be tolerated
debug:    false         // If debug statements should be allowed
eqeq:     false         // If == should be allowed
es5:      false         // If es5 syntax should be allowed
evil:     false         // If eval should be allowed
forin:    false         // If for in statements need not filter
newcap:   false         // If constructor names capitalization is ignored
nomen:    true          // If names may have dangling _
plusplus: true          // If increment/decrement should be allowed
regexp:   true          // If the . should be allowed in regexp literals
undef:    false         // If variables can be declared out of order
unparam:  false         // If unused parameters should be tolerated
sloppy:   true          // If the 'use strict'; pragma is optional
sub:      false         // If all forms of subscript notation are tolerated
vars:     true          // If multiple var statements per function should be allowed
white:    true          // If sloppy whitespace is tolerated
css:      false         // If css workarounds should be tolerated
cap:      false         // If upper case html should be allowed
on:       false         // If html event handlers should be allowed
fragment: true          // If html fragments should be allowed
browser:  true          // If the standard browser globals should be predefined
devel:    false         // If logging should be allowed (console, alert, etc.)
node:     false         // If node.js globals should be predefined
rhino:    false         // If the rhino environment globals should be predefined
windows:  false         // If ms windows-specific globals should be predefined
indent:   4             // The indentation factor
maxerr:   50            // The maximum number of errors to allow
maxlen:   200           // The maximum length of a source line
global:   UWA, widget

Sample usage:

<meta name="strictMode" content="true" />

Thumbnail

Purpose: gives a link to a thumbnail image or the service's logo.
The value of the "content" attribute MUST be a valid URL.
Preferred size is 120px wide by 60px high.
Preferred file format is PNG. GIF and JPEG SHOULD also be accepted.

Sample usage:

<meta name="thumbnail" content="http://www.example.com/app-logo.png" />

Screenshot

Purpose: gives a link to a screen-capture of the app in action.
The value of the "content" attribute MUST be a valid URL.
Preferred size is 280px wide.
Preferred file format is PNG. GIF and JPEG SHOULD also be accepted.

Sample usage:

<meta name="screenshot" content="http://www.example.com/app-full.png" />

Application head Preferences

The UWA format should be able to work as-is on any mobile-, Web- or desktop-platform, as long as it supports standard web technologies such as XHTML, JavaScript and CSS. Failing that, it has been designed to be easily parse-able thanks to XML, in order to be recompiled into the target platform's specific inner functioning.
Since XHTML doesn't offer any portable solution for preferences handling, UWA defines its own, through an XML extension of XHTML.

Text preference

XHTML Syntax:

<widget:preference type="text" name="url" label="User Name" defaultValue="John Doe" ></widget:preference>

Expected rendering:
SHOULD be rendered as a standard <input> tag of type "text", or the platform's equivalent rendering.

Sample rendering:

<label for="m_userName">User Name:
<input id="m_userName" type="text" name="userName" value="John Doe" /></label>

Boolean preference

XHTML Syntax:

<widget:preference type="boolean" name="displayImg" label="Display images" defaultValue="true" ></widget:preference>

Expected rendering:
SHOULD be rendered as a standard <input> tag of type "checkbox", or the platform's equivalent rendering.

Sample rendering:

<label for="m_displayImg">Display images:
<input id="m_displayImg" type="checkbox" name="displayImg" checked="checked" /></label>

Hidden preference

XHTML Syntax:

<widget:preference type="hidden" name="lastSearchQuery" defaultValue="" ></widget:preference>

Expected rendering:
SHOULD be rendered as a standard <input> tag of type "hidden", or the platform's equivalent rendering.
It may also be not rendered at all, and be handled directly by the platform using JavaScript or the platform's own methods.

Sample rendering:

<input id="m_lastSearchQuery" type="hidden" name="lastSearchQuery" />

Password preference

XHTML Syntax:

<widget:preference type="password" name="authPass" label="User password" ></widget:preference>

Expected rendering:
SHOULD be rendered as a standard <input> tag of type "password", or the platform's equivalent rendering.

Sample rendering:

<label for="m_authPass">User password:
<input id="m_authPass" type="password" name="authPass" value="" /></label>

List preference

XHTML Syntax:

<widget:preference type="list" name="category" label="Category" defaultValue="1st">
    <widget:option value="all" label="all"></widget:option>
    <widget:option value="1st" label="First category"></widget:option>
    <widget:option value="2nd" label="Second category"></widget:option>
    <widget:option value="3rd" label="Third category"></widget:option>
</widget:preference>

Expected rendering:
SHOULD be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering.

Sample rendering:

<label for="m_category">Category:</label>
<select id="m_category" name="category">
    <option value="all">all<option/>
    <option value="1st" selected="selected">First category<option/>
    <option value="2nd">Second category<option/>
    <option value="3rd">Third category<option/>
</select>

Range preference

XHTML Syntax:

<widget:preference type="range" name="limit" step="1" min="1" max="7" defaultValue="5" label="Number of items to display"></widget:preference>

Expected rendering:
SHOULD be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering.
In case the platform implements an HTML5-enabled web engine (with Web Forms 2.0 support), the Range preference should be rendered as a standard HTML5 <input> tag of type "number".

Sample HTML 4 / XHTML 1 rendering:

<label for="m_limit">Number of items to display:
<select id="m_limit" name="limit">
    <option value="1" />1</option>
    <option value="2" />2</option>
    <option value="3" />3</option>
    <option value="4" />4</option>
    <option value="5" selected="selected" />5</option>
    <option value="6" />6</option>
    <option value="7" />7</option>
</select>
</label>

Sample Web Forms 2.0 rendering:

<label for="m_limit">Number of items to display:
<input id="m_limit" name="limit" type="number" step="1" min="1" max="7" defaultValue="5" /></label>

Other head content

Title

Purpose: gives the name to the application and default application's title value.

Sample usage:

<title>My Application Name</title>

Icon link

Purpose: gives a link to the application's logo, in the usual favicon format.
Preferred size is 16px wide by 16px high, using 256 colors.
Preferred file format is PNG. GIF and JPEG are also accepted.
The format MAY also be ".ico".

Sample usage:

<link rel="icon" type="image/x-icon" href="http://www.example.com/app/favicon.ico" />
<link rel="icon" type="image/png" href="http://www.example.com/app/favicon.png" />

Rich-icon link

Purpose: some platforms require a bigger logo than the usual thumbnail (i.e., Apple Dashboard, Windows Vista, Yahoo! Widget, etc.). In such cases, compilers should make use of the rich-icon as the app's main graphic identifier instead of the regular icon.
Preferred size is 128px wide by 128px high.
Preferred file format is PNG. GIF and JPEG are also accepted.

Sample usage:

<link rel="rich-icon" type="image/png" href="http://www.example.com/app/richicon.png" />

Standalone emulation files

While not mandatory, these two files may be added to the application's <head> section in order to test-drive the application in standalone mode. They give the application a basic styling and a basic JavaScript framework.
They therefore only exist for such purpose, and MAY be entirely ignored by implementing platforms.

Sample usage:

<!-- Application Standalone emulation files -->
<link rel="stylesheet" type="text/css" href="//uwa.netvibes.com/lib/c/UWA/assets/css/standalone.css" />
<script type="text/javascript" src="//uwa.netvibes.com/lib/c/UWA/js/UWA_Standalone_Alone.js"></script>

Notably, there MAY be other <script> tags within the file, the other one being where the application's JavaScript code resides.

Externals Javascript and CSS files

To use external libraries inside your UWA app you just have to inject the script or link tags after the Standalone emulation files.

Sample usage:

<!-- Application Standalone emulation files -->
<link rel="stylesheet" type="text/css" href="//uwa.netvibes.com/lib/c/UWA/assets/css/standalone.css" />
<script type="text/javascript" src="//uwa.netvibes.com/lib/c/UWA/js/UWA_Standalone_Alone.js"></script>

<!-- Application External files -->
<link rel="stylesheet" type="text/css" href="http://example.com/MyCompany/MyStyle.css" />
<script type="text/javascript" src="http://example.com/MyCompany/MyLib.js"></script>

Implementations SHOULD resolve the relative paths using the current url of the UWA app.

Application body content

JavaScript usage

XHTML usage

You can populate the body tag of the UWA app with XHTML tags. You just need to respect the XHTML standard see examples bellow.

Note that for the JavaScript file the same rules than JavaScript usage apply.

<!-- Bad formated XHTML -->
<img class=myClassName src="http://example.com?id=1&size=16">
<input id="MyFancyInput" value=">">

<!-- Properly formated XHTML -->
<img class="myClassName" src="http://example.com?id=1&amp;size=16"/>
<input class="MyFancyInput" value="&gt;"/>

Here a list of the XHTML basics rules:

Implementations SHOULD not tolerate non properly formated XHTML for security.

Styling with CSS

UWA is based on Web-standards, so apps can make use of any HTML element and attribute, (like table or style), as well as CSS.

But for real styling, app can rely on CSS. CSS rules has to be defined in the app file's style tag.

Here is an example:

<head>

...

<!-- Application Style Source -->
<style type="text/css">
.myContainer a,
.myContainer a:link,
.myContainer a:hover,
.myContainer a:active,
.myContainer a:visited {
    text-decoration: none;
    border: none;
}
</style>

...

</head>

<body>
    <!-- Application XHTML Source -->
    </div class="myContainer">
        <a href="href://example.com">My Website Link</a>
    </div>
</body>

App SHOULD NOT to rely on an external CSS file:

App styles MUST only target the app's element, not general page elements:

UWA JavaScript Runtime

UWA provides a JavaScript Framework to application developers to help them handle day to day tasks such as updating the DOM or sending Ajax requests.
UWA both extends and limits JavaScript, in order to offer more tools to developers, and to ensure that applications do not interfere with each other.

widget object

The widget object is the equivalent of window object for UWA Application.

widget properties

widget.title
The current title of the Application.
It is set by the widget.setTitle method.

widget.icon
The current icon of the Application.
It is set by the widget.setIcon method.

widget.metas
The current metas of the Application.

widget.lang
The current user's language/dialect, depending on their platform settings (default: "en").

widget.locale
The current user's locale, depending on their platform settings (default: "us").

widget.dir
The current user's language direction, depending on their platform settings (default: "lft").

widget.preferences
A collection of the current prefences object that reflect the declared XML preferences.

widget.body
A DOM element that contains the content for the application.

widget methods

widget.setTitle(title)
Sets the disaplayed title of the application. Overrides the file's <title> tag value.
Implementation MUST trigger the 'onUpdateTitle' event only if not the same as the previous one.

widget.setIcon(url)
Sets the disaplayed icon of the application. Overrides the file's <link> tag value.
Implementation MUST trigger the 'onUpdateIcon' event only if not the same as the previous one.

widget.setAutoRefresh(delay)
Sets the automatic refresh rate value. Overrides the autoRefresh meta, if present. Argument delay is expressed in minutes.
Argument MUST be expressed as an integer.

widget.log(string)
If the "debugMode" meta tag is set to "true", SHOULD log the given string to the platform's JavaScript console (i.e. with Firebug).
Equivalent to JavaScript console.log().
Argument MUST be a string.

widget DOM methods

widget.setBody(content)
Replace the content of the widget body by another.

Sample usage:

widget.setBody([
    {
        tag: 'div',
        'class': 'myHeader'
    },
    {
        tag: 'div',
        'class': 'myContent',
        html: [
            {
                tag: 'a',
                text: 'My Link',
                styles: {
                    color: 'red'
                },
                event: {
                    click: function (event) {
                        // My Click Handler
                        UWA.Event.stop(event);
                   }
                }

            }
        ]
    },
    {
        tag: 'div',
        'class': 'myFooter'
    },
]);

widget.addBody(content)
Add content to current widget body.
Behaves like widget.setBody(content) except that add content to the widget body instead of replace it.

widget.getElements(selector)
Gets all descendants elements whose match a CSS selector.
Behaves like the HTMLElement.querySelectorAll except for queries starting with “>”, “~” and “+”.

Sample usage:

// Get all anchors in the element
widget.getElements('a');

// Get all elements with "myClass" class
widget.getElements('.myClass');

// Get all anchors with "myClass" class
widget.getElements('a.myClass');

// Get all anchors with a title attribute in the element
widget.getElements('a[title]');

// Get all "p" children elements under a container,
// whose parent is a div that contains the class 'highlighted'
widget.getElements('div.highlighted > p');

widget.getElement(selector)
Gets the first descendant element who matches a CSS selector.
Behaves like the HTMLElement.querySelector except for queries starting with “>”, “~” and “+”.

Sample usage:

// Get the first anchor in the element
widget.getElement('a');

// Get the first element with "myClass" class
widget.getElement('.myClass');

// Get the first anchor with "myClass" class
widget.getElement('a.myClass');

// Get the first anchor with a title attribute in the element
widget.getElement('a[title]');

// Get the first "p" children element under a container,
// whose parent is a div that contains the class 'highlighted'
widget.getElement('div.highlighted > p');

widget.createElement(tagName, options)
Creates a new element according to the provided "tagName" and options.

Sample usage:

var myDiv = widget.createElement('div');

var myButton = widget.createElement( 'input',{
    'class': 'myButton', // Quote require arround property due "class" reserved word
    type: 'submit',
    value: 'Update'
});

widget Preferences methods

These methods are specifically built to handle the applicaton's preferences.

widget.getValue(name)
Retrieves the value of the given preference name. Returns a string.
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.getInt(name)
Retrieves the value of the given preference name. Returns an integer.
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.getBool(name)
Retrieves the value of the given preference name. Returns a boolean value (true/false).
If the preference is not of the corresponding type, implementations MUST apply a type conversion.
Argument MUST be an existing preference name.

widget.setValue(name, value)
Sets a preference with the given value.
First argument MUST be an existing preference name.
Second argument SHOULD be a value of a type supported by the preference. If this is not the case, implementations MUST apply a type conversion.

widget EventListener methods

widget.dispatchEvent(name, args, bind, dispatched)
Executes the listeners method associated with the given event name.

widget.addEvent(name, listener, bind, priority)
Add an listener method associated with the given event name.

widget.removeEvent(name, listener)
Specified name ONLY: Remove ALL events of given name.
Specified name AND listener function: Remove that given listener from this event name's stack.

widget EventListeners

The following event Methods should be declared only once, by assigning a function or block of code to them.
The following events are for internal use, but a developer can trigger them using widget.dispatchEvent method. Unless said otherwise, all of these events MUST or SHOULD be implemented.

onLoad
Triggered when the application is launched.
This event MUST be declared in any widget, in order for any of the widget's JavaScript code to be executed.
Implementations MUST trigger this event once the application is done loading.

onRefresh
Triggered when the application is refreshed (manually or programmatically).
Implementations SHOULD trigger this event when preferences values are updated. If this event is not declared, the onLoad event SHOULD be triggered instead.

onResize
Triggered when the application is resized (manually or programmatically).
Implementations SHOULD trigger this event when the size of the application container is resized (for instance, when the user resizes the containing column, or changes the number of columns on the page).

onKeyboardAction
Triggered when a key is pressed within the application's area.
Implementations may first require the user to click within the application's area in order to limit the interaction to that application only.
Implementations SHOULD pass the key-code as first argument of the event.

onSearch
Triggered when a search is performed from within the platform.
Implementing platforms that feature a search form MAY trigger this event, with the search query as first argument, so that the application may use it to further perform a search with its own data, if such a thing is possible.
Implementation is not mandatory.

onResetSearch
Triggered when a search is reseted from within the platform.
Implementing platforms that feature a search form MAY trigger this event, so that the widget may use it to further reset the last search, if such a thing is possible.
Implementation is not mandatory.

onUpdateIcon
Triggered when the widget's icon is modified.
Implementations MUST trigger it when widget.setIcon() is used.
Implementations MAY also trigger for internal reasons.

onUpdateTitle
Triggered when the widget's title is modified.
Implementations MUST trigger it when widget.setTitle() is used.
Implementations MAY also trigger for internal reasons.

Implementations MAY also trigger it when the preferences are updated or displaying.
Implementations MAY also trigger it for internal reasons.

onUpdatePreferences
Triggered when a widget's preference is added.
Implementations SHOULD trigger this event when a preferences is added (manually or programmatically).

onShowEdit
Triggered when widget's preference form is displayed.
Implementations SHOULD trigger this event when a preferences form appear or is displayed.

onHideEdit
Triggered when widget's preference form disappear.
Implementations SHOULD trigger this event when a preferences form disappear or exited.

UWA object

The UWA JS Runtime provide an UWA object into each instance of UWA application. This object contains a JavaScript Framework that provide a full toolkit to build your JavaScript applications.

This chapter will only introduce few methods and namespace description, see UWA Js Runtime documentation for full documentation.

UWA methods

extend
Copies all the properties from the second passed object to the first passed Object.

Example:

var a = {key1: 'value1a', key2: 'value2a'};
var b = {key2: 'value2b', key3: 'value3b'};
UWA.extend(a, b);
// will return {key1: 'value1a', 'key2: 'value2b', key3: 'value3b'}

merge
Copies all the properties from the second passed object to the first passed Object if it not exists already.

Example:

var a = {key1: 'value1a', key2: 'value2a', key3: null};
var b = {key2: 'value2b', key3: 'value3b', key4: 'value4b'};
UWA.merge(a, b);
// will return {key1: 'value1a', 'key2: 'value2a', key3: 'value3b', key4: 'value4b'}

typeOf
Returns the type of an object.

Example:

UWA.typeOf({a: 4});                                  // "object"
UWA.typeOf(Math);                                    // "object"
UWA.typeOf(new ReferenceError);                      // "error"
UWA.typeOf([1, 2, 3]);                               // "array"
UWA.typeOf(new Date);                                // "date"
UWA.typeOf(/a-z/);                                   // "regexp"
UWA.typeOf(new Number(4));                           // "number"
UWA.typeOf(new String("abc"));                       // "string"
UWA.typeOf("");                                      // "string"
UWA.typeOf(true);                                    // "boolean"
UWA.typeOf(new Boolean(true));                       // "boolean"
UWA.typeOf();                                        // false
UWA.typeOf(window.myUndefined);                      // false
UWA.typeOf(null);                                    // false
UWA.typeOf("x" - 111);                               // false

See UWA Js Runtime documentation for full list of methods available into UWA namespace.

UWA.Data methods

request
This method is used to get the content of an external data source even on another domain than current domain. It can be used to retrieve or set any kind of data: text-based, XML, JSON or a feed. The other Ajax methods (getText(), getXml(), getJson(), getFeed()) are all shortcut methods to specific uses of request(). This method is also the only way to perform HTTP POST request, as well as authenticated requests.

Example:

// Create callbacks methods
var MyObject = {
    lastRequest: null,
    onComplete: function (textResponse) {
        // your parsing code
    },
    onError: function (error) {
        // your error handler code
    }
};

// Cancel previous request (for sample only, not usefull in all cases)
if (MyObject.lastRequest) {
    MyObject.lastRequest.cancel();
}

// Launch request on "http://example.org/api?param1=value1&param2=value2"
MyObject.lastRequest = UWA.Data.request('http://example.org/api', {
  method: 'get',
  type: 'text',
  data: {
    param1: 'value1',
    param2: 'value2'
  },
  onComplete: MyObject.onComplete,
  onFailure: MyObject.onError
});

See UWA Js Runtime documentation for full list of methods available into UWA.Data namespace.

UWA.Utils objects

This UWA Objet namespace is dedicated to non EcmaScript String and Array manipulation methods, Cryptography methods, Client features detection (UWA.Utils.Client) and Application Intercommunication (UWA.Utils.InterCom).

See UWA Js Runtime documentation for full list of methods and sub-namespace available into UWA.Controls namespace.

UWA.Controls objects

This namespace is dedicated to UWA UI components that we call "Controls". Most of Controls implement UWA.Controls.Abtract and UWA.Class.

Example of available Controls:

See UWA Js Runtime documentation for full list of Controls available into UWA.Controls namespace.

Reference

All references are normative unless marked "Non-normative".
[JSLint]
"JSLint: The JavaScript Code Quality Tool", Douglas Crockford, 2002.
Available at http://www.jslint.com/lint.html.
[IETF RFC 2119]
"Key words for use in RFCs to Indicate Requirement Levels", Scott Bradner, Author. Internet Engineering Task Force, March 1997.
Available at http://www.ietf.org/rfc/rfc2119.txt.
[IETF RFC 3236]
"The 'application/xhtml+xml' Media Type", M. Baker, P. Stark, January 2002.
Available at http://www.ietf.org/rfc/rfc3236.txt.
[DOM]
"Document Object Model (DOM) Level 1 Specification", Lauren Wood et al., 1 October 1998.
Available at http://www.w3.org/TR/REC-DOM-Level-1.
[DOM2]
"Document Object Model (DOM) Level 2 Core Specification", A. Le Hors, et al., 13 November 2000.
Available at http://www.w3.org/TR/DOM-Level-2-Core.
[XML]
"Extensible Markup Language (XML) 1.0 Specification (Second Edition)", T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, 6 October 2000.
Available at http://www.w3.org/TR/REC-xml.
[XMLNS]
"Namespaces in XML", T. Bray, D. Hollander, A. Layman, 14 January 1999.
XML namespaces provide a simple method for qualifying names used in XML documents by associating them with namespaces identified by URI.
Available at http://www.w3.org/TR/REC-xml-names.
[HTML]
"HTML 4.01 Specification", D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999.
Available at http://www.w3.org/TR/html401.
[CSS2]
"Cascading Style Sheets, level 2 (CSS2) Specification", B. Bos, H. W. Lie, C. Lilley, I. Jacobs, 12 May 1998.
Available at http://www.w3.org/TR/REC-CSS2.

Acknowledgements

The Netvibes team would like to thank all the contributors to the UWA project, our corporate sponsor, and you, the UWA users. Please visit us sometime soon at https://dev.netvibes.com