Latest Version: 1.3RC4
Editors:
Copyright 2006-2012 Netvibes, a Dassault Systèmes company. All rights reserved.
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.
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.
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.
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.
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>
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:
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/">
,
<widget:preferences>
element with <widget:preference>
tags.
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.
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.
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." />
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" />
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" />
Purpose: provides a description of the application.
Implementations could use within their application directory.
Sample usage:
<meta name="description" content="A descriptive description" />
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" />
Purpose: indicates the version of UWA JavaScript API used throughout the app.
For internal use only.
Sample usage:
<meta name="apiVersion" content="1.3" />
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" />
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" />
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" />
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" />
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" />
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.
<widget:preferences>
element.
<widget:preferences>
element per application.
<widget:preference>
tag within the <widget:preferences>
element.
<widget:preference>
MUST be closed with </widget:preference>
element.
<widget:option>
MUST be closed with </widget:option>
element.
<widget:preferences>
element and its content MUST be well-formed
XML.
Notably, XHTML entities SHOULD be escaped.
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>
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>
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" />
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>
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>
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>
head
content
Purpose: gives the name to the application and default application's title value.
Sample usage:
<title>My Application Name</title>
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" />
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" />
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.
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.
body
content
document
and window
objects SHOULD NOT be used.
Most of their methods/properties are available through the widget
object, while others are not available/recommended.
widget.onLoad
Event Listener.
JavaScript code SHOULD NOT be triggered from the window.onLoad
Event Listener.
Note that there are circumstances where the UWA environment may not be
fully ready until widget.onLoad
event is triggered.
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&size=16"/> <input class="MyFancyInput" value=">"/>
Here a list of the XHTML basics rules:
class=myClassName
versus quoted class="myClassName"
).value=">"
versus escaped value=">"
).src="http://example.com?id=1&size=16"
versus escaped src="http://example.com?id=1&size=16"
).class
attribute rather than id
to target element because the current document may contains more
than one instance of your UWA app (e.g id="MyFancyInput"
versus class="MyFancyInput"
).Implementations SHOULD not tolerate non properly formated XHTML for security.
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 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
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.
document.createElement(tagName);
.new Element(tagName, 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.
widget.setBody()
is used
widget.addBody()
is used
widget.body
node subtree is modified
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¶m2=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:
UWA.Controls.Form
to easily build HTML form
UWA.Controls.Pager
to build you content pagination
UWA.Controls.TabView
to build multiple content navigation using tabs
See UWA Js Runtime documentation for full list of Controls available into UWA.Controls namespace.