This identifier is a system generated and unique string identifying this widget. It is used as the first part of URLs using the widget URL protocol.

Example:

img.src = 'widget://' + widget.identifier + '/resources/logo.png';

You may set this function to do some kind of processing when the widget is being hidden. An example is stopping the widget from periodically polling some service for data. This function gets called after the widget is hidden with a call to widget.hide().

Example:

widget.onHide = function ()
{
    pollInterval = 24000;
}

You may set this function to do some kind of processing when the widget is being shown after having been hidden. An example is starting to periodically poll some service for data. This function gets called after the widget is shown with a call to widget.show().

Example:

widget.onShow = function ()
{
    pollInterval = 12000;
}

The origin URL represents the unique and stable URL this widget was downloaded from. This property is used in relation to security by allowing or disallowing download from certain URLs. The property can also be used to provide other users with a link to where they can download the widget.

Example:

a.textContent = 'Learn more about this widget';
a.href = widget.originURL;

The mode is one of 'widget', 'docked', 'application' or 'fullscreen', depending on what mode the widget is currently in. A widgetmodechange event will be fired on the widget object if the mode changes.

Example:

if (widgetMode == 'application')
{
    removeChrome();
}

Calling this method will get the user's attention in some way. This will vary with the device. On desktop, the task bar entry for the widget will blink. Mobile phones which support this may for example flash the display, play a sound or make the phone vibrate.

Example:

if ( dataReceived )
{
    widget.getAttention();
}

Calling this method will hide the widget from view. It will not appear as a window or in the task bar, but will continue to run in the background. If the widget is already hidden, calling this method will do nothing.

When the widget is hidden, the widget.onHide function is called.

Example:

hideButton.addEventListener( 'click', function () { widget.hide(); }, false; )

This method lets you programatically open a URL in the browser. The URL is opened in a new tab in the last active window. Only URLs which are allowed by the security policy of the widget may be opened. If the widget's config.xml file or any system configuration disallows access to the the given URL, the call will fail silently.

Example:

button.addEventListener( 'click', function ()
{
    color = document.getElementById('colorSelect').value;
    widget.openURL('http://www.buzz.com?color=' + color);
}, false );

Get the value stored for the given key in the widget preference store. If there is no value for the given key, an empty string is returned.

Example:

username = widget.preferenceForKey('username');

This method will store the given value in the widget in the widget preference store for the given key. The preference store is unique to this widget and any values stored in it are persisted if the widget is reloaded or closed and started again. If a value for the given key already exists, it is silently overwritten.

Storing an empty string for the given key will create an entry for the given key with an empty string as its value.

Calling this method with null as the value will unset any value previously set.

Note that the order of the arguments. This and the name of the method is this way to promote compatibility with Dashboard widgets.

Example:

widget.setPreferenceForKey( 'gautamc', 'username' );

Calling this method will bring the widget out of hiding, reopening the window and showing it in the task bar for the desktop browser. An example is opening the widget when interesting data or requests were received, by calling widget.show() in the callback to widget.showNotification(). If the widget is already visible, calling this method will do nothing.

When the widget is shown, the widget.onShow function is called.

Example:

if (dataReceived && showOnNewData )
{
    widget.show();
}

Calling this method will show a notification with the given message to the user in some way. This will vary with device. On desktop, a popup similar to messages about new mails.

If the user accepts the notification, for example by clicking on it, the given callback is called. If the user ignores the notification, the callback is never called.

This feature can be used to bring a widget out of hiding when something significant occurs, for example that new weather data has been received.

Example:

if ( messageReceived )
{
    widget.showNotification( 'A new message received from ' + message.from, updateView );
}