This document describes Opera Widgets 1.0, third edition, and covers all aspects of Opera Widgets, including the packaging format, the configuration file config.xml, and scripting interfaces for working with widgets.
This document and its appendices represent the required solutions for creating and running interoperable Opera Widgets across target platforms, both on devices and desktop.
The purpose of this specification is to provide an implementation reference for Widgets in the Opera browser. The specification builds on the currently implemented features in Opera 9.50.
The key words ”MUST”, ”MUST NOT”, ”REQUIRED”, ”SHALL”, ”SHALL NOT”, ”SHOULD”, ”SHOULD NOT”, ”RECOMMENDED”, ”MAY”, and ”OPTIONAL” in this document are to be interpreted as described in [RFC2119].
Unless specifically marked otherwise, this document is considered to be normative.
Widgets are a bundled archive of files, as specified by the [ZIP] file format specification, with exception that the ‘Deflate64’ compression method for the [ZIP] file format is not supported.
Every Opera Widget must contain the following two files:
When a widget is packed as a zip file for distribution, the author must choose one of two different ways of structuring the files and folders within the widget.
The config.xml and index.html at the root of the .zip file, with any associated resources, such as scripts and images, in the same directory or subdirectories.
An alternative approach is to put all of the files belonging to the widget inside a directory located at the root of the zip file. The name of this folder, should be the same as the compressed zip file. When this alternative approach is used, there must not be multiple folders at the root of the zip file's hierarchy. If there are multiple folders at the root, loading the widget must fail.
When a widget is loaded a virtual root path for a file system is established based on the location of the config.xml, where this root path is in the same folder where config.xml exists.
When widgets are served from web servers, they must be
served with the content-type
application/x-opera-widgets
.
Widgets should have the file extension .wgt to be properly recognized as widgets. However, if the content-type is being used correctly, as above, other extensions, such as .zip should work.
The necessary information for a widget UA to run a widget is stored in a file named config.xml, located as previously specified in the Widget packaging chapter of this specification. This file contains information about the widget neccesary to establish the initial view for the widget file. A widget file is an XML 1.0 document following [XML10]
A minimal config.xml looks like the following, giving the widget a name, and widget’s initial viewport the size 300×300 CSS pixels:
<widget>
<widgetname>
Hello World!
</widgetname>
<width>
300
</width>
<height>
300
</height>
</widget>
When presented to the end user, whitespace characters in config.xml elements are normalized the following way:
This presentation is consistent with setting the value normal for the white-space attribute in [CSS21]
When processing config.xml, Opera will ignore leading
and trailing whitespace for all elements, equivalent to getting the
textContent
DOM attribute value.
widget
elementThe widget
element is the root element of the
config.xml file, and must be present in the widget
configuration file as the only element in the document root, per [XML10].
widget
elementdefaultmode
attributeThe defaultmode
attribute MAY be
present on the widget element, in which case it contains the
preferred rendering mode for a widget.
Valid attribute values are:
widget
: The widget is typically rendered
without user chrome, and the widget is assumed to have
control over its own window size.application
: The widget is assumed to be
rendered in a viewport size determined by the widget engine,
optionally using the initial rendering dimensions specified in
config.xml as a suggestion. Further, where applicable, the
widget engine should also render application
chrome.fullscreen
: This mode is identical to the
application
mode, except that the widget is
expected to be rendered using the entire available viewport.
A user agent may render the widget using application
chrome.If the specified rendering mode is not available to the widget, the widget should fall back to render in another mode, in the order application, fullscreen, widget.
If the attribute is missing, it is assumed to be present with
the value widget
.
dockable
attributeThe dockable
attribute
specifies whether the widget supports full docking, where a web
document is displayed, as opposed to displaying limited information
consisting of e.g. the Widget status, title and icon.
Valid values for the dockable
attribute
is a case sensitive string, having the values 'yes', 'true' and
'dockable' represent dockable widgets. All other values are to be
interpreted as the value false
, and the
widget is not providing a docked mode.
transparent
attributeIf
a widget does not require transparency features, i.e. the prefered
presentation is for the entire widget viewport to be opaque, the
transparent
attribute can be used to
control the widget's use of transparency.
Valid values for the transparent
attribute is a case sensitive string, having the values 'yes',
'true' and 'transparent' representing transparent widgets. All other
values must be interpreted as 'false', meaning the widget
will not be transparent.
If the attribute is missing, and the current computed widget mode
is 'widget', it is assumed to be present with the value
transparent
, hence implying that the
default presentation is to support transparency. If the computed
value of the widget mode is 'application' or 'fullscreen', the
widget is expected to default to
false
, not supporting transparency. A
user agent may override these values, depending on
platform requirements.
<widget>
widgetname
elementThe widgetname
element must be present in
config.xml as a child of the widget
element, and
must contain a string whose purpose is to provide a
human-readable title for the widget. This title will be used in
application menus to provide a descriptive title for the widget.
width
elementThe width
element should be present in
config.xml as a child of the widget
element. After
whitespace normalization, and stripping of any leading/trailing
white-space the value of this element must be interpretable
as a string representation of an integer, containing only the
characters [0–9].
This integer value is treated as the widget’s size along the horizontal axis, measured in CSS pixels, as per section 4.3.2 of [CSS21], and should represent the inner width of the widget, or the entire drawable area along the horizontal axis.
If the attribute is missing, or its value is invalid, it is assumed to be present, with a value of 100
Please see the note on virtual viewports when implementing on a target where chromeless windows can not be dragged offscreen.
height
elementThe height
element should be present in
config.xml as a child of the widget
element. After
whitespace normalization, and stripping of any leading/trailing
white-space the value of this element must be interpretable
as a string representation of an integer, containing only the
characters [0–9].
This integer value is treated as the widget’s size along the vertical axis, measured in CSS pixels, as per section 4.3.2 of [CSS21], and should represent the inner height of the widget , or the entire drawable area along the horizontal axis.
If the attribute is missing, or its value is invalid, it is assumed to be present, with a value of 100
Please see the note on virtual viewports when implementing on a target where chromeless windows can not be dragged offscreen.
<widget>
widgetfile
elementThe widgetfile
element is an optional child element of
the widget
element. If present, the purpose of this
element is to point the widget to an alternative start
file for the widget. When present, the element must
contain a valid relative path reference to an alternative start file
for the widget. The path reference must be URL encoded
author
elementThe author
element is an optional child element of the
widget
element. If present, the purpose of the element is
to provide information about the widget’s author. This element
has a few child elements, as specified below.
name
elementIf the name
element is present in the document, this
element should be present as a child element of the
author
element. If present, this element must be
a child of the author
element, and its value
must be a string that contain a human-readable representation
of the widget author’s name.
organization
elementIf the organization
element is present in the document, this
element may be present as a child element of the
author
element. If present, this element must be
a child of the author
element, and its value
must be a string that contains a human-readable name for an
organization representing, or represented by the widget author.
email
elementIf the email
element is present in the document, this
element may be present as a child element of
author
. When present, this element must contain
a string, whose value should be a valid e-mail adress as specified by
[RFC2822]. This e-mail address
should be a live e-mail address widget users can use to
contact the widget author.
link
elementIf the link
element is present, the
link
element may be present as a child element
of author
. If the link
element is present,
this element must contain a string, whose value must be a
syntactically valid IRI as specified by [RFC3987]. It is further recommended that the
IRI represented also resolves. The intended presentation to an
end-user is to present this IRI as a link the user can visit.
description
elementThe description
element is an optional element of the
widget
element. If present, the element should contain a
string that serves as a human-readable short plain-text description of
the widget.
icon
elementThe icon
element is an optional element of the
widget
element. The purpose of this element is to provide
a pointer to an icon file contained within the widget archive that the
underlying operating system and widget player can display to the end
user where displaying an application icon is natural.
The element must contain a string that is a relative IRI in accordance with [RFC3987], with the root path being the same as the location of the config.xml file.
When present, the IRI must resolve, and must reference an image, in either of the following formats: [PNG10], [GIF89] or [SVG].
The icon
element can optionally have
width
and height
attributes.
The config.xml may contain more
than one icon
element. If multiple icon elements are
present, the widget engine may choose the icon that best matches the
display requirements of the widget engine, even if none of the
specified icons exactly match the size.
When the user agent chooses an icon, it should select the icon that most closely matches the size implied by the width and height attributes. If there are no matches, the User Agent should choose the one that is closest to matching the size.
If multiple icon elements with the same size exist, Opera should choose the last of the icons present in config.xml, although a widget engine may choose to always use an icon in a particular format, such as PNG, even when an appropriately sized icon in other formats exist.
security
elementThe security
element is an optional child element of
the widget
element and may be present in the
document. The purpose of the security
element is to act
as a container for security-related settings in a widget. The elements
of the security
elements are described below.
access
elementThe access
element is an optional element of the
security
element. The child elements of
access
declares which protocols, hosts, ports, and paths
the widget may use. Missing child elements are interpreted to mean
“any”. An example is that if the host
element is missing,
the widget is requesting access to all hosts.
Furthermore, all of the specified child elements may occur multiple times, and the product of all these is used. The child elements are as defined below.
protocol
The protocols the widget will be using to contact external servers. All protocols, except the file protocol is permitted.
host
The host
element establishes which hostnames may
be contacted. The hostnames are exact matches. This means that a
widget specifying www.example.com must not
be able to contact example.com. IP addresses
may also be used as values.
port
The port
element establishes which port numbers
the widget will be using. The value is either a number, a range of
numbers separated by a dash, e.g. 1024-2048
, or a comma-separated list of ports,
e.g. 80, 1337
.
path
The path
element specifies the path part of the
URI a widget may contact.
content
elementWidgets may use third-party plugins, and Java content.
Plugins that wants to use these features must request this
access by adding an optional content
element as a child
of the security
element. When present, the
content
element must contain at least one of the
two attributes specified below, and it may contain both.
java
attributeThe possible values of this attribute are respectively the
case-insensitive strings "yes" or "no".
When a widget wants access to use Java content embedded in the
widget, the value of this attribute _must_ be "yes".
If the java
attribute is not present, the attribute
is assumed to be present, and have the associated value "no".
plugin
attributeThe possible values of this attribute are respectively the
case-insensitive strings "yes" or "no".
When a widget wants access to use Java content embedded in the
widget, the value of this attribute _must_ be "yes".
If the plugin
attribute is not present, the attribute
is assumed to be present, and have the associated value "no".
If a content
element is not present in a
config.xml’s security section, or if a security section is not
present in a widget, the element is assumed to be present with the
value of both java
and plugins
set to
”no”.
The widget access model is summarised as follows:
An intranet is defined based on the resolved IPv4 address of a host name. The following IPv4 ranges are defined as intranets:
All other IP ranges than these are defined as Internet addresses.
The following example contains a security section would indicate that the widget should be allowed to contact the domains example.com and example.org using either the https or http protocols, but only to the path ’/good’ on ports 80,1337 and ports in the range 2048–4096. In addition, the widget wants access to Java, but not plugins.
<security>
<access>
<protocol>http</protocol>
<protocol>https</protocol>
<host>example.com</host>
<host>example.org</host>
<path>/good</path>
<port>2048-4906</port>
<port>80,1337</port>
</access> <content java="yes" plugins="no" />
</security>
id
elementThe id
element is an optional child element of the
widget
element. If present, this element may be
used to establish a concept of identity of the widget that
may be used for recognizing version updates and similar. The
syntax requirement for this element is to have three required
child elements, containing strings, as specified below.
host
This element is required, and must be a fully qualified domain name naming the host from which the widget was downloaded.
name
This element is required, and must be a
string that is unique to the domain specified in the
host
element.
revised
This element is required, and must be a string in the [W3CDTF] format, with the added constraint that both year and month are made mandatory parts of the date. The date used should be a date chosen by the author, with enough granularity to represent two different, with the exception that both Year and Month is made mandatory.
Widgets are client-side web applications for displaying local or remote content, typically on a user desktop, or appearing as a locally installed application on a device. Widgets can be displayed in several different contexts, or modes, as described below. An installed widget may support several of the modes, but will only display one at a time
Widget authors that wish to support styling widgets separately for widgets
in different modes, may use the -o-widget-mode
CSS
media feature, using one of the four previously
defined widget modes as the value to specify the styling. Some examples
follow:
Hiding UI elements in application mode:
@media all and (-o-widget-mode:application) {
/* We don't need to display fake user chrome controls, since
real chrome is provided */
.fakeChrome { display: none; }
}
Changing the font-size for docked (microwidget) mode
@media all and (-o-widget-mode:docked) {
body { font-size: 80%; }
}
It is also possible to specifically style something in the case that the platform supports the -o-widget-mode attribute, by not specifying a value:
@media all and (-o-widget-mode) {
div.friendlyMessage {
content: "I will be displayed if I am a modern widget";
}
}
The purpose of the widget
object is to expose
functionality specific to widgets that either should not or
must not be available to scripts running on regular web
pages. The widget object implements the Widget interface:
interface Widget {
readonly attribute DOMString identifier;
readonly attribute DOMString originURL;
readonly attribute DOMString widgetMode;
void openURL(in DOMString URL);
String preferenceForKey(in DOMString key);
void setPreferenceForKey(in DOMString value,
in DOMString key);
/* Widget attention */
void getAttention();
void showNotification(in DOMString msg, in Function callback);
/* Widget window managment; */
attribute Function onshow;
attribute Function onhide;
void show();
void hide();
}
identifier
attribute, of type DOMString
, readonlyThe identifier
attribute, of type
DOMString, serves as a universally unique identifier of the widget
instance in question. The value must always contain a
valid, unique DOMString.
originURL
attribute, of type DOMString
, readonlyWhen a widget is downloaded and instantiated from any other protocol than file://, the value of this attribute should always be a valid URL locating the widget. The value of the attribute should not be escaped, or otherwise encoded.
widgetMode
attribute, of type DOMString
, readonlyThe widgetMode
attribute identifies the
current rendering mode for the widget. The value of this attribute
should be one of the values widget,
application, fullscreen or docked.
The value must always correspond to the current rendering
mode of the widget.
openURL
() methodThe openURL
() method on the widget object
takes a String as an argument. Further, this string must be a
valid URL as defined by
[RFC3987]. When this method is called with a
valid URL, the URL should be opened in the system browser on the
system on which the widget runs.
Note that restrictions to what URLs can be opened using openURL, as defined in the security section of this specification. Specifically this applies:
preferenceForKey
() methodThe preferenceForKey()
method takes a String argument,
key. When called, this method returns a string that has
previously been stored with the setPreferenceForKey
method, or
undefined if the key key does not exist.
setPreferenceForKey
() methodThe setPreferenceForKey()
method takes two String arguments,
preference and key. When called, this methods takes the
string in the preference argument, and stores it with the key named
in the key argument for later retrieval using the
preferenceForKey
() method. To delete a previously
stored key, the setPreferenceForKey
() method is
called with the value null in the preference argument,
and the name of the key to be deleted in the key argument.
getAttention
()
method.The getAttention
() method takes no arguments and
returns void. When called, this method should use an appropriate means to
bring the widget to the user's attention.
Methods of bringing the user's attention to the widget may for instance include flashing the taskbar icon, or raise
the widget's urgency. The getAttention
() method should not, however try to grab the window focus.
showNotification
()
method.The showNotification
() method takes two
arguments, the first being a String with the message text, and a second
argument being a function to function as a callback when the notification is
accepted.
When showNotification
() is called, the system is
expected to display a notification containing the message text. The message
text is a DOMString and whitespace within the string, including newlines is
significant.
Upon the user acknowledging the notification, the callback function is called without any arguments.
onshow
attribute, of type
FunctionWhen a function is specified in the onshow
callback, e.g. the value of the attribute is non-null and a valid function
reference, the callback will be called whenever the widget's state changes
from being hidden to being visible.
Note that the onshow callback should not be dispatched if a visible widget gets focus.
onhide
attribute, of type
FunctionWhen a function is specified in the onhide
callback,
e.g. the value of the attribute is non-null and a valid function reference,
the callback will be called whenever the widget's state changes from being
visible to being hidden.
Note that the onshow callback should not be dispatched if a visible widget loses focus.
show
() methodThe show
() method takes no arguments, and returns
no value. When the method is invoked a widget that has previously been in a
hidden state will be shown. If the widget is already in a shown state,
invoking show will perform no action.
hide
() methodThe hide
() method takes no arguments, and returns
no value. When the method is invoked a widget that has previously been in a
shown state will be hidden. If the widget is already in a hidden state,
invoking show will perform no action.
The show
() method takes no arguments,
widgetWindow
interfaceA widget's initial dimensions are controlled by the width
and height
elements in the config.xml file. In addition to this, a widget
can be resized dynamically using Javascript, using the extensions below.
interface widgetWindow {
attribute DOMString status;
attribute DOMString defaultStatus;
void moveTo(in Integer pos_x, in Integer pos_y);
void moveBy(in Integer delta_pos_x, in Integer delta_pos_y);
void resizeTo(in Integer x_size, in Integer y_size);
void resizeBy(in Integer delta_x_size, in Integer delta_y_size);
}
status
attribute, of type
DOMStringThe status
attribute is used to display a
status message in a widget overview/managment page, or similar. It is used
to display a short piece of textual information to the user. An example
could be a stock ticker that changes to show the value of the last updated
stock, to then revert to displaying a default status message.
When set, the status
message is kept until it
is either cancelled by clicking in the widget document that set the status,
or the value of the attribute is set to the empty string.
defaultStatus
attribute, of type DOMStringThe defaultStatus
attribute, when set
provides a default status message which is to be displayed in a widget
managment page, or other widget overview mechanism
When the value of this attribute is non-null, an action that cancels the
window.status should bring up the contents of the
defaultStatus
attribute in place of the
original/system-provided status message. If the value is null or the empty
string, the widget runtime should fall back to a system-provided message.
moveTo
() methodWhen the widget is rendering in a context where the position of the
widget may be changed, the moveTo
() method
sets the position of the widget. The method accepts two arguments,
pos_x
and pos_y
, both Integer values, which
are x and y coordinates defined by a coordinate system the flat
cartesian surface whose origin (0,0) is at the top left corner of the
available viewport, with the coordinate space having x values
increasing when going right, and y values increasing when going
down.
moveBy
() methodWhen the widget is rendering in a context where the position of the
widget may be changed, the moveBy
() method
moves the widget in the x and/or y direction, using the arguments, the
integer values delta_pos_x
and delta_pos_y
,
defined by a coordinate system the flat cartesian surface whose origin
(0,0) is at the top left corner of the available viewport, with the
coordinate space having x values increasing when going right, and y
values increasing when going down. Negative values for both arguments
are accepted, and a negative value for either argument means that the
widget should move towards respectively the top or the left of the viewport.
resizeTo
() methodWhen the widget is rendering in a context where the size of the
widget may be changed, the resizeTo(
) method
sets the new size of the widget, using the Integer arguments
size_x
and size_y
, respectively. Setting the
size using resizeTo() must produce exactly the same
dimensions the for the widget, as if they appeared in the
config.xml
values for the width and height elements. Both the
size_x
and size_y
arguments value must be
larger than 1, and a call to resizeTo
() with
smaller values should result in no change to the widget dimensions.
resizeBy
() methodThe resizeBy
() method should resize the
widget by adding the values of the argument delta_x_size
to the current value for the widget width, and add the
delta_y_size
to the current height of the widget,
measured in pixels. The resulting dimensions gathered from such
addition must produce exactly the same dimensions the for the
widget, as if the calculated dimensions appeared in the
config.xml
values for the width and height elements. Negative values for
both arguments are accepted, as long as the resulting calculated
size remains larger than 1×1 pixel, in which case the
resizeBy
() method should result in no
change to the widget size.
When a successful resize of the widget has been performed using any of the four mentioned mentioned, the resulting values should be stored, and used in place of any values specified in config.xml.
WidgetModeChangeEvent
interfaceWhen the value of the -o-widget-mode
CSS attribute
changes, the widgetmodechange
is dispatched on the
Widget
object. When the event is
dispatched, the event object passed as an argument to the event
listener must have a widgetMode
attribute that
corresponds to the current rendering mode. The value must be one of
those mentioned for the widgetMode
attribute
on the Widget
interface.
The WidgetModeChangeEvent
must not
bubble, must not be cancelable and must implement the Event interface
[DOM3Events]. The event has no namespace (Event.namespaceURI is
null).
interface WidgetModeChangeEvent : Event { readonly attribute DOMString widgetMode; void initMediaTypeChangeEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString widgetModeArg); // For DOM Level 3 support void initMediaTypeChangeEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, }
ResolutionEvent
interfaceThe resolution
is dispatched on the
widget
object when the width or height
values of the attached display object changes. It must not bubble,
must not be cancelable and must implement the Event interface
[DOM3Events]. The event has no namespace (Event.namespaceURI is
null).
When dispatched, the event object must have two
attributes, width
and height
corresponding
to the new available width and height for the widget. These two values
should correspond to the values availWidth
and
availHeight
on the Screen
interface.
interface ResolutionEvent : Event { readonly attribute int width; readonly attribute int height; void initMediaTypeChangeEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in int widthArg, in int heightArg); // For DOM Level 3 support void WidgetModeChangeEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in int widthArg, in int heightArg); }
The purpose of Widget autodiscovery is to enable clients who know a URI of a web page to identify and find the location of a widget associated with said web page. A widget-aware web client should offer a mechanism that exposes the presence of the widget to the user, and offer a mechanism for installing the widget.
A Widget autodiscovery element is a link element, as defined in
section 12.3. of [HTML401]. As with other
link elements, an autodiscovery element may appear in the
head
element of an HTML or XHTML document, but it must
not appear inside the body
element. An example
autodiscovery element looks like this:
<link
type="application/x-opera-widgets" rel="alternate"
href="http://widgets.example.com/example.zip" title="An Example
Widget"
/>
When a widget autodiscovery element appears in a [HTML401] or [XHTML10] document, the element shares all the syntax rules and restricitions of other markup elements.
A document may contain multiple autodiscovery elements. A User Agent should present an installation option for all autodiscovered widgets to the user, listed in the order of appearance in the source code.
A User Agent that only presents one autodiscovered widget to the user should choose the first autodiscovered widget for installation whenever the user opts to install the widget.
The type attribute must be present in a widget autodiscovery element. The value of the type attribute must be an Internet Media type, and the media type must be application/x-opera-widgets.
The rel attribute must be present in a widget autodiscovery element. As defined in section 6.12 of [HTML401], the value of the rel attribute is a space-sparated list of keywords. The list of keywords must include the keyword alternate in uppercase, lowecase, or mixed case.
The href attribute must be present in a widget autodiscovery element, and its value must be the URI of the widget. The value may be a relative URI, and if so, clients must resolve it to a full URI, using the document’s base URI. The URIs must conform to [RFC3987].
The title attribute may be present in a widget autodiscovery element. A User-Agent should treat the value of the title attribute as a human-readable title for the widget, and the User-Agent may present this title to the user.
This appendix to the widget specification provides algorithm to determine widget size and position, for cases where either the window manager provides the initial widget size, or on platforms where widgets need to separate the concepts of "viewport size" and
The following algorithm is used for determining the start size of a widget.
Use the following algorithm to determine the initial widget position
These are implementation guides for resizing, positioning and widget types, this algorithm is considered informative.
Certain window managers and systems may not allow chromeless windows to be dragged off the viewport, leaving the widget with little surface area in which the user can move the widget. This section describes an algorithm to mitigate the problem. On such platforms, this algorithm, or a workalike must be implemented to facilitate a good user experience.
Note that the width
element represents the canvas
width, and not the window width. Under most circumstances, the
window width and canvas width should be the same, but certain
platforms may implement a window width that is different from the
canvas width, using the following algorithm:
Note that the height
element represents the canvas
height, and not the window height. Under most circumstances, the
window height and canvas height should be the same, but certain
platforms may implement a window height that is different from the
canvas height, using the following algorithm: