Class: UWA.Environment

UWA/Environment. UWA.Environment

new UWA.Environment(options)

The Environment object provide base methods to run an UWA Widget execution Environment and load Widgets.

It's an abstract object, and must be extended to be useful. The object must fill <html> property with DOM elements (at least body), in the <onInit> or <onRegisterWidget> methods for example.

Run Stack:

var environment = new UWA.Environment();
// Periodical[init]: init 100ms (document.body && !that.inited)
this.dispatchEvent('onInit');
this.inited = true;

var widget = environment.getWidget();
-> this.registerWidget();
// Periodical[register]: register 100ms (that.inited && !that.registered)
this.dispatchEvent('onRegisterWidget');
this.registered = true;

environment.launchWidget();
// Periodical: launch 100ms (that.isDataReady() && that.registered)
this.widget.launch();
this.widget.dispatchEvent('beforeLoad');
this.widget.dispatchEvent('onLoad');
this.widget.dispatchEvent('afterLoad');
Parameters
Name Type Description
options Object

Options hash or a option/value pair.

Mixes In

  • UWA.Class.Timed
  • UWA.Class.Events
  • UWA.Class.Debug
  • UWA.Class.Options

Index

Members

Methods

Members

name :String

Current platform name where environment running (e.g "netvibes").

Type
  • String

registered :Boolean

Flag to know if a widget is registered. A widget is not registered until the environment is loaded

Type
  • Boolean

launched :Boolean

Flag to know if a widget is launched. A widget is not launched until the environment is registered

Type
  • Boolean

widget :UWA.Widget

Current widget registered in this environment.

Type
  • UWA.Widget

html :Object

HTML Dom elements related to this environment

Type
  • Object
Properties:
Name Type Description
title String

Title HTML element
edit String

Edit HTML element
body String

Body HTML element
icon String

Icon HTML element

features :Object

Stores environment's available features. See module:UWA/Environment.UWA.Environment#hasFeature.

Type
  • Object

loadInlinedWidget

Load a widget for inline use.

Example
var environment = new UWA.Environment();

// Load JSON Widget object
environment.loadInlinedWidget('http://example.org/widget.html, {
   onComplete: function(widget, environment) {

       // Set widget data
       widget.setValues({
           activeTab: 'tab8',
           my_text: 'my data...'
       })

       // Manipulate widget object
       widget.setTitle('Updated Title');
       widget.setIcon('http://example.org', '`true`');


       // Launch the widget
       environment.launchWidget();
   }
});

// Load a widget using existent XHTML
var myWidget =
'<?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 Metas -->' +
'         <title>Title of the Widget</title>' +
'         <meta name="author" content="John Doe" />' +
'         <meta name="description" content="A descriptive description" />' +
' ' +
'         <!-- Application Standalone emulation files -->' +
'         <link rel="stylesheet" type="text/css"' +
'             href="http://uwa.netvibes.com/lib/c/UWA/assets/css/standalone.css" />' +
'         <script type="text/javascript"' +
'             src="http://uwa.netvibes.com/lib/c/UWA/js/UWA_Standalone_Alone.js">' +
' ' +
'       </head>' +
'       <body>' +
'            <p>Hello world!</p>' +
'       </body>' +
'</html>';

var environment = new UWA.Environment();

// The first argument is only used as a key cache, it does not have
// to be an URL
environment.loadInlinedWidget('widget42', {
   fetcher: myWidget,
   onComplete: function (widget, Environment) {
       // same as above example
   }
});

// Json Wigdet argument format
var myWidget = {
   "title": "Hello World",
   "icon": "http://example.org/favicon.png",
   "richIcon": "http://example.org/richIcon.png",
   "metas": {
       "version": "1.0.0",
       "apiVersion": "1.3",
       "autoRefresh": "10",
       "description": "Display Hello World for UWA",
       "author": "Netvibes",
       "strictMode": "`false`",
       "debugMode": "`false`",
       "screenshot": "http://example.org/screenshot.png",
       "thumbnail": "http://example.org/thumbnail.png"
   },
   "plugins": [],
   "preferences": [[
       {
           "type": "text",
           "name": "my_text",
           "label": "My text pref",
           "defaultValue": ""
       },
       {
           "type": "password",
           "name": "my_password",
           "label": "My password pref",
           "defaultValue": ""
       },
       {
           "type": "boolean",
           "name": "my_checkbox",
           "label": "My checkbox pref",
           "defaultValue": ""
       },
       {
           "type": "hidden",
           "name": "my_hidden",
           "defaultValue": ""
       },
       {
           "type": "range",
           "name": "my_range",
           "label": "My range pref",
           "defaultValue": "10",
           "step": "5",
           "min": "5",
           "max": "15"
       },
       {
           "type": "list",
           "name": "my_list",
           "label": "My list",
           "defaultValue": "Value1",
           "options": [
               {
                   "label": "Label1",
                   "value": "Value1"
               },
               {
                   "label": "Label2",
                   "value": "Value2"
               },
               {
                   "label": "Label3",
                   "value": "Value3"
               }
           ]
       }
   ],
   "body": "<p>Loading...</p>",
   "script": "var MyWidget = { onLoad: function() { widget.body.setContent('Hello World!'); }; \n widget.onLoad = MyWidget.onLoad;",
   "style": ".myClassName { color: red; }"
};

var environment = new UWA.Environment();

// The first argument is only used as a key cache, it does not have
// to be an URL
environment.loadInlinedWidget('widget42', {
   fetcher: myWidget,
   onComplete: function (widget, Environment) {
       // same as above example
   }
});

onViewRequest

Try to change the widget view. This event can be triggered from the widget by <UWA.Widget.requestView> or manually within the environment.

Methods

onLoad()

Triggered when the widget 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.

onResize()

Triggered when the widget 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(key)

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

Parameters
Name Type Description
key String

The pressed key's code

onSearch(query)

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 widget may use it to further perform a search with its own data, if such a thing is possible.

Parameters
Name Type Description
query String

The search query

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.

onUpdatePreferences(preferences)

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

Parameters
Name Type Description
preferences Array

An Array of preferences in their JSON serialization

dispatchInit()

Dispatch "onInit" event to setup the environment html elements and events, when container readyState is interactive.

See:

hasFeature(name, options) → {Boolean}

Check if the environment supports a feature. Please see environments documentation for a list of supported features.

Parameters
Name Type Argument Description
name String

the name of the feature
options Object <optional>

hash of key/value to check if the feature supports those options
Returns

true if the environment support it

Type
Boolean

getWidget() → {UWA.Widget}

Returns the widget currently registered in the Environment. If no widget is registered, the Environment creates one and registers it.

Returns

The UWA.Widget instance (maybe newly created) registered widget.

Type
UWA.Widget

registerWidget(widget)

Registers a Widget into the execution Environment. Once done, fire the onRegisterWidget callback.

Parameters
Name Type Description
widget Object

The <UWA.Widget> instance to register

launchWidget(data, readOnly)

Launch the registered widget by fire the widget.launch method. If needed, wait until the environment is fully loaded and a widget registered.

Internal or advanced use only.

Parameters
Name Type Argument Default Description
data Object

Widget's data values
readOnly Boolean <optional>
 false

true if the widget is currently read only for the viewer

destroy()

Destroy the elements and its children of widgets. Remove all events and remove the elements from the dom. Clear all Delayeds and Periodicals timers. Remove current environment widget Instance from <UWA.Widgets.instances>.

registerMenus()

Register menus to be displayed in widget chrome.

Note: widgets can add specific menu items using setMenu methods in their own code.

onUpdateMenu(menus)

Called when a menu item has been added or removed through widget.setMenu or widget.removeMenu.

The entire menu is rebuilt. This method can be overrided by derivated classes.

Parameters
Name Type Description
menus Array

Menu descriptors

onMenuExecute(menuItem)

Event fired when a menuItem is executed

Parameters
Name Type Description
menuItem Object

the menu item descriptor

isDataReady() → {Boolean}

Check if Environment Data Storage is ready.

Returns

true if environment data storage is ready else false.

Type
Boolean

getAllData() → {Object}

Retuns all the widget data stored in the environment, used internally to launch the widget. The Environments implementations should override it if it does not use a Storage instance in the data property.

Returns

All the datas of the widget.

Type
Object

getData(key) → {Void}

Retrieve data key current value.

Parameters
Name Type Description
key String

The key of value to get
Returns

Current key value.

Type
Void

setData(key, value) → {Void}

Set current data key value.

Parameters
Name Type Description
key String

The key of value to get
value String

The value of value to store
Returns

Current key value.

Type
Void

deleteData(key) → {Void}

Delete data key from storage.

Parameters
Name Type Description
key String

The key of value to get
Returns

Previous key value.

Type
Void

dispatchEvent(name, args, bind)

Executes the listeners method associated with the given event name.

Internal or advanced use only.

Parameters
Name Type Description
name String

the event name (e.g. "onUpdateTitle");
args Array

Array of parameters that should be passed to each listener
bind Object

Context on which listener will be executed (object that should represent the this variable inside listener function)
Returns

Nothing, but calls the listeners associated with the given event name.

loadWidget(url, options) → {this}

Asynchronously load an UWA widget from url source.

Internal or advanced use only.

Example
<div class="app" tabindex="1">
 <script type="text/javascript">
     (function () {
         var environment = new UWA.Environment();

         environment.loadWidget('http://uwa.netvibes.com/apps/samples.php', {
             onComplete: function (widget, environment) {

                 // Set widget data
                 widget.setValues({
                      activeTab: 'tab8',
                      my_text: 'my data...'
                 })

                 // Manipulate widget object
                 widget.setTitle('Updated Title');
                 widget.setIcon('http://example.org', '`true`');

                 // Launch the widget
                 environment.launchWidget();
             }
         });
     }());
 </script>
</div>
Parameters
Name Type Description
url String

The URL of the UWA widget source
options Object

Options hash or a option/value pair.

Properties
Name Type Argument Description
onComplete Function <optional>

Called with the resulting Widget instance as first argument.
onFailure Function <optional>

Called if an error occurs
onTimeout Function <optional>

Called if a timeout occurs while fetching widget informations
embedded Function <optional>

Used as a boolean to load the widget as embedded or inlined‡
Returns
Type
this

loadEmbeddedWidget(url, options) → {this}

Load widget from url and render it using <UWA.Embedded>.

Internal or advanced use only.

Parameters
Name Type Description
url String

the URL of the UWA widget source
options Object

a JavaScript object containing setting/value pairs This object can take a handful of settings, the only required one being 'onComplete', because you need to always set a callback method that will receive the widget and environment parameter. That method must have one parameter to receive the widget object returned by the environment.
Returns
Type
this

fetchJsonWidget(sourceURL, options)

Parameters
Name Type Description
sourceURL String

The widget URL
options Object
Properties
Name Type Argument Default Description
server Object <optional>
 UWA.hosts.exposition

The exposition server to use
onComplete Function <optional>

The callback used to return the widget informations

fetchXmlWidget(sourceURL, options)

Asynchronously fetch <widget> from an XHTML widget raw source.

Internal or advanced use only.

Parameters
Name Type Description
sourceURL String

the widget URL
options Object
Properties
Name Type Argument Description
onComplete Function <optional>

The callback used to return the widget informations
onFailure Function <optional>

The callback used when the request fails (see Data.request)
onTimeout Function <optional>

The callback used when the request timeouts (see Data.request)
cache Function <optional>

The cache time to pass to the widget server (see Data.request)

filterExternalResources(type, Array) → {Array}

Allow the environment to prevent loading some resources, or change resources URL. Override this method in an Environment implementation.

Parameters
Name Type Description
type String

The resource type
Array Array

of String resourges: the resources URL included in the widget
Returns

the resources to include.

Type
Array

onRefresh()

Triggered when the widget is refreshed (manually or programmatically). Implementations SHOULD trigger this event when preferences values are updated. If this event is not declared, the <UWA.Widget.onLoad> event will be triggered instead.

onUpdateIcon(url)

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

Parameters
Name Type Description
url String

The url of the icon. The URL should include the protocol (http://)

onUpdateTitle(title)

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

Parameters
Name Type Description
title String

The title of the widget. Can contain HTML code

onUpdateCounter(count, type)

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

Parameters
Name Type Argument Description
count Number | Boolean | String

The number of results or status for the current search/unread items
type String <optional>

The number of results type (e.g 'search').

onEdit()

Triggered when edition of preferences begin.

onShowEdit()

Triggered when preferences showing.

endEdit()

Triggered when edition of preferences ending.

onHideEdit()

Triggered when preferences hiding.

onCloseEdit()

Triggered when preferences is closed (even by cliking on 'Done' or by clicking on the cross icon).

onOpenURL(url) → {Boolean}

Open an url into a new environment browser window.

Implementation can differ between environments.

Behavior differ between execution environments: - open the page in an iframe on the same screen - open the page in a new window/tab - open the page in a new browser window (desktop widgets)

Parameters
Name Type Description
url String

The url to open in a new window
Returns

true if it successfully opens the url (according to the subprotocol)

Type
Boolean

onViewChange(view)

Triggered when the view changed, it saves the view is the widget.

Parameters
Name Type Description
view Object

Wiew parameters, like for <onViewRequest>

onViewError(view)

Triggered when the view fails to change.

Parameters
Name Type Description
view Object

view parameters, like for <onViewRequest>, with one additional parameter 'error' representing the error message.