Opera Widgets specification 1.0, fourth edition

By Chris Mills

This article is deprecated

We recently announced that we're discontinuing Widgets and Unite from Opera 12, in favour of Opera Extensions. (Already developed a Widget? See converting widgets to Opera extensions.)

Abstract

This document describes Opera Widgets 1.0, fourth 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 represents the required solutions for creating and running interoperable Opera Widgets across target platforms, both on devices and desktop.

This is an update of the Opera Widgets specification 1.0, third edition

Opera Software Specification

Editors: Arve Bersvendsen, Opera Software ASA, arveb@opera.com; Marcos Cáceres, Opera Software ASA, marcosc@opera.com

Abstract

This is the fourth edition of the Opera Widgets 1.0 specification. This document describes all aspects of Opera Widgets, including the packaging format, the widget configuration document, and scripting interfaces for working with widgets.

Scope of this Document

This document and its appendices represent the required solutions for creating and running interoperable Opera Widgets across target platforms, both on devices and desktop.

1 Introduction

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 10 (the user agent).

1.1 Conformance Requirements

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].

Unless specifically marked otherwise, all sections are normative.

2 Opera widget package

An Opera widget package is a .Zip archive, as specified by the [ZIP] file format specification.

Authors must not use the ‘Deflate64’ compression method for the [ZIP] file format, as it is not supported by the user agent.

An Opera widget package must contain the following two files:

widget configuration document (config.xml) – a widget configuration document containing information necessary to initialize the widget. The widget configuration document should contain the widget’s name and geometry, and may also contain:
- Widget description
- Author information
- Icon reference
- Security information
Start file (index.html) – this is the main document for the widget; the file that is run when the widget is initialized by the user agent.

2.1 Widget folder structure

When a widget is packaged for distribution, an author must choose one of two different strategies for structuring the files and folders within the zip archive:

Strategy 1 - place the widget configuration document and start file at the root of the Opera widget package. Any associated files, such as scripts, stylesheets and images, are in the same directory or in subdirectories.
Strategy 2 - All of the files belonging to the widget inside a single directory located at the root of the package. The author should name this folder with the same name as the compressed zip file.

If strategy 2 is used by the author, there must not be multiple folders at the root of the zip file's hierarchy.

If there are multiple folders at the root, but not configuration file, the user agent must fail to load the widget.

When a widget is loaded, the user agent must establish a a virtual root path for a file system based on the location of the config.xml, where this root config.xml exists.

2.2 Content type

When an author serves an Opera widget package from a Web server, it must be labeled with the HTTP content-type application/x-opera-widgets.

A user agent must process resources from the Web labeled as application/x-opera-widgets as an Opera widget package, regardless of file extension.

2.3 File extension

An author should use the file extension .wgt for Opera Widgets, particularly for widgets that are intended to be distributed via non-http means.

From a local file system, a user agent must attempt to process files with the .wgt file extension as an Opera widget package.

3 Widget configuration document

The widget configuration document contains metadata about the widget that establishes the initial viewport size for the start file.

An author must place the widget configuration document at the root of the package or within a folder (so long as that folder is the only resource at the root of the package).

An author must name the widget configuration document "config.xml" (the name of the configuration document must be in lower case form).

A widget configuration document must be a well-formed [XML10] document and should be encoded as UTF-8.

If a user agent encounters a configuration document that is not well-formed XML, the user agent must fail to load the widget.

A minimal widget configuration document 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>
</widget>

3.1 White space

When processing a widget configuration document, the user agent must normalize white space: this means that thee user agent ignores leading and trailing whitespace for all elements (equivalent to getting the textContent attribute value from an Element [DOM3Core]).

In addition, when presented to the end user, whitespace characters in attributes of elements of the widget configuration document elements must be normalized by the user agent in the following way:

Leading and trailing whitespace is stripped
Multiple whitespace characters are normalized to single whitespace characters.

Note: this presentation is consistent with setting the value normal for the white-space attribute in [CSS21].

4 Elements of the widget configuration document

This section describes the XML elements and corresponding attributes that can be used within a widget configuration document. This section also describes the expected structure and usage of those elements.

A user agent must treat all attribute values case sensitively.

4.1 The `widget` element

The widget element is the root element of a widget configuration document.

The defaultmode attribute

The defaultmode attribute represents the preferred widget mode for a widget. Valid attribute values are:

widget: The widget is typically rendered by the user agent without user chrome; the widget has control over its own window size.
application: The widget is assumed to be rendered in a viewport size determined by the user agent. A user agent may use the initial rendering dimensions specified in the widget configuration document. Further, where applicable, the user agent should also render application chrome.
fullscreen: This mode is similar 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 user agent should fall back to rendering the widget in another mode. The fallback order a user agent must follow is application, fullscreen, and finally widget.

If the attribute is missing, the user agent must assume the value widget.

The dockable attribute

The dockable attribute specifies whether the widget supports docking where a Web document is displayed, as opposed to displaying limited information consisting of, for example, the Widget status, title and icon. For more information on the dockable widget mode, refer to the Widget modes section.

Valid values for the dockable attribute are ‘yes’, ‘true’ or ‘dockable’. All other values must be interpreted by the user agent as the value false, meaning that the widget does not provide a docked mode.

The transparent attribute

An author can use the transparent attribute to control the widget's use of background transparency.

Valid values for the transparent attribute are the values ‘yes’, ‘true’ or ‘transparent’. All other values must be interpreted by the user agent as ‘false’, meaning that the user agent must not make the widget's background transparent.

If the transparent attribute is missing, and the current computed widget mode is ‘widget’, then the user agent must behave as if the value transparent for this attribute had been set to true.

If the computed or declared value of the widget mode is ‘application’ or ‘fullscreen’, but the transparent attribute is missing, then the user agent must behave as if the value of this attribute had been declared to be false.

A user agent may override the value of the transparent attribute, depending on platform requirements.

The network attribute

The network attribute allows and author to declare their intention to access the public network and/or private networks. The network attribute takes a space-separated made up of the following values: public and/or private. The values are interpreted as follows:

private: The widget only requires access to the private network.
public: The widget only requires access to the public network.
public private or private public: The widget requires access to both public networks and/or private networks.

When the attribute is missing, or not a valid value, the user agent must not allow the widget to access resource in the public network or private network range (i.e., totally deny access to the network).

It is optional for an author to use the network attribute; however, without declaring this attribute, the user agent will not grant the widget access to the public network IP range or the private network IP range.

The user agent must compare network requests the user agent's own security policy for accessing the network.

4.2 The `widgetname` element

The widgetname element contains 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.

Authors must use a widgetname element in a widget configuration document, as a direct descendent of the widget element.

4.3 The `width` element

The width element is a value in CSS pixels, as per section 4.3.2 of [CSS21], that represents a widget’s draw-able area along the horizontal axis.

An author MAY use the width element and the element must be a direct descendent of the widget element.

After whitespace normalization, a user agent must interpret the resulting value as an integer (i.e., a string that only contains the characters [0–9]).

If the attribute is missing, or its value is invalid, then the user agent must use the value "300".

Please see the note on virtual viewports when implementing on a target where chromeless windows can not be dragged off-screen.

4.4 The `height` element

The height element is a value in CSS pixels, as per section 4.3.2 of [CSS21], that represents a widget’s draw-able area along the vertical axis.

An author MAY use the height element and the element must be a direct descendent of the widget element.

After whitespace normalization, a user agent must interpret the resulting value as an integer (ie a string that only contains the characters [0–9]).

If the attribute is missing, or its value is invalid, then the user agent must use the value "300".

Please see the note on virtual viewports when implementing on a target where chromeless windows can not be dragged off-screen.

4.5 The `widgetfile` element

The widget file points the widget to a start file for the widget. When present, the element must contain a valid relative path to a start file.

An author must not %-encode all path names.

It is recommended that authors use this element.

4.6 The `author` element

The author element is a container element for metadata about the widget’s author. It is optional for an author to use this element. This element can contain the following child elements:

The name element:: The name element represents the name, or names, of the author of the widget. It is optional for an author to use this element. If used, this element must be a direct descendent of the author element.
The organization element:: The organization element represents the name of an organization that the author is affiliated with. It is optional for an author to use this element. If used, this element must be a direct descendent of the author element.
The email element:: The email element represents an e-mail address for the author of the widget. It is optional for an author to use this element. If used, this element must be a direct descendent of the author element.
The link element: The link element represents an IRI which the author associates with him or her self. It is optional for an author to use this element. If used, this element must be a direct descendent of the author element.

It is recommended that authors use this element.

4.7 The `description` element

The description element is a short plain-text description of the widget.

It is recommended that authors use this element.

4.8 The `icon` element

The icon element is a path to an icon file contained within the Opera widget package that the user agent can display to the end user in appropriate contexts.

When used, the icon element must point to a file that is one of the supported icon formats.

The icon formats that a user agent must support are: [PNG10], [GIF89] and [SVG].

An author may use zero or more icon elements.

If the author has used multiple icon elements, the user agent must choose the icon that best matches the display requirements of the user agent, even if none of the icons match the exact dimensions of the render context.

The icon element can have width and height attributes:

width attribute: The value of width is an unsigned integer, representing the desired width of the icon in device pixels.
height attribute: The value of height is an unsigned integer, representing the desired height of the icon in device pixels.

It is optional for authors to use the width and height attributes of an icon element.

When the user agent chooses an icon, it should select the icon that most closely matcheps 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 of the render context.

If multiple icon elements with the same size exist, the user agent should choose the last of the icons present in the widget configuration document.

A user agent may choose to exclusively use an icon in a particular format (e.g., such as PNG).

It is recommended that authors use one or more of this element.

4.9 The `feature` element

A feature is a runtime component or functionality beyond the default set of functionality a user agent provides to a widget at runtime (e.g., the file IO API). Authors must explicitly request, via the feature elements, that the user agent make particular features available to the widget at runtime. Whether widget is granted access to a feature depends on the security policy and security privileges granted to the widget by the user agent (i.e., a user agent is under no obligation to grant access to any particular feature).

It is optional for authors to use the feature element; when used, the feature element must be a direct descendent of the widget element.

name attribute: The name of a feature, as represented by a URI. The use of the name attribute represents an author's intention to make use of a feature within a widget. If an author has used a feature element, it is required that authors use the name attribute.
required attribute: The required attributes indicates to the user agent if the feature is required for correct operation of the widget. In other words, if the feature must be made available by the user agent for the widget to function correctly, if at all. The default value for when the value of this attribute is missing is "true". It is optional for authors to declare the required attribute.

An author may use zero or more param elements as child elements of the feature element.

4.10 The `param` element

The param element allows an author to declare parameters, which may be associated and used by feature (e.g., the name and values provided by a param element can be used to configure a particular feature).

It is optional for authors to use the param element; when used, the param element must be a direct descendent of the feature element.

A user agent must ignore any param element that is not a direct descendent feature element.

name attribute: A string that represents the name of this parameter.
value attribute: A string that represents the value of this parameter.

4.11 The `id` element

The id element establishes an identity for a widget.

It is optional for authors to use the id element; However, when used, the id element must be a direct descendent of the widget element and must contain all three host, name, and revised elements (one of each, in any order).

The host element: A fully qualified domain name that identifies the host from which the widget can be downloaded.; If used by an author, this element must be a direct descendent of the id element.
The name element: A string that is unique to the domain specified in the host element.; If used by an author, this element must be a direct descendent of the id element.
The revised element: A string in the [W3CDTF] format.; When used, the author must include the Year and Month components of the [W3CDTF]; other components are optional.; If used by an author, this element must be a direct descendent of the id element.

4.12 The `security` element

A widget's configuration document can contain a "security declaration": a declaration of the protocols, hosts, ports, and paths that the widget will attempt to access.

The security declaration is represented as the security element in the configuration document.

The security element works in conjunction with the network attribute of the widget element. Without the declaration of a network attribute, the user agent must deny access to the network.

The user agent defines a default security policy which affects what the author may gain access to. System administrators may also define a local security policy document which overrides the default policy. The default security policy is described in the Security model section of this specification. The security policy document is out of the scope of this specification.

When a security element is used, an author must use one of the following elements as a child of the security element:

The access element
The content element

It is optional for authors to include a security element; when used, the security element must be a direct descendent of the widget element.

4.13 The `access` element

The access element is a container element whose child elements declare which protocols, hosts, ports, and paths the widget can use.

The expected child elements of the access element are:

The protocol element
The host element
The port element
The path element

An author may use zero or more protocol, host, path, or port elements within an access element.

A user agent must treat undeclared child elements of the access element to mean that an author is requesting access to the full capabilities afforded by the semantics of the missing element. An example is that if the host element is missing, the widget is requesting access to all hosts.

The protocol element: The protocol element is used to determine which protocols a widget should have access to. When missing from the configuration document, the element is assumed to be present three times, with the values ‘widget’, ‘http’ and ‘https’.
: If any protocol element is declared, then the user agent must initially deny access to the http and https protocol (but continue to allow access to the ‘widget’ URI scheme); The user agent must grant access to ‘http’ or ‘https’ only if the author explicitly requests access to these protocols through a protocol element.; The value of this element is the name of the scheme that widget will be using to contact external servers (e.g., http, https).; A user agent must not grant access to the file protocol; if a request is made to access the file protocol, the user agent must behave as if this protocol element is not present in the widget configuration document (i.e., ignore this element).
The host element: The host element establishes which hostname or IP address the widget will want to contact. A user agent must treat the value of host as an exact match. This means, for example, that the user agent will not allow a widget specifying www.example.com to contact example.com.
The port element: 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).; When missing from an access element, the port element is assumed to be present, matching all ports, and when a widget requests access to a resource, it can do so on every port. It should however be noted that there may be certain port numbers for which the user agent has disabled access for security reasons, and a configuration override cannot change these.; When port numbers are specified for a protocol in an access element, the port numbers specified are the only ones by which a widget can communicate.

The path element: The path element specifies the path part of the URI a widget can contact.

4.14 The `content` element

The content element allows authors to disable support for plugins within their widgets.

Authors not requiring the use third-party plugins content must use the content element as a child of the security element.

If a content element is not present in a widget configuration document’s security section, or if a security section is not present in a widget, the element is assumed to be present with the value plugins set to "yes".

plugin attribute: The possible values of this attribute "yes", "no", "true", "false", "plugin". " yes", "true" and "plugin" mean that the widget will use plugin as embedded content (e.g., a Flash file). All other values, included disallowed values, means that the widget will not use plugin as embedded content.

5 Security model

Conceptually speaking a widget is "loaded" onto a computer before it is "run"; so, its home domain is the computer on which it is running. In addition, many widgets accomplish their task by "mashing-up" information from various sources on the Web. Thus, a widget needs greater rights than Web pages in order to be useful.

The main security concern is that a widget that accesses pages on an intranet can steal information. And there is also a concern about leaking information about the widget's user from one Web site to another.

This document specifies what widgets are normally allowed to do, how they can be granted privileges, and how their privileges can be adjusted. Actions are controlled by defaults, with overrides from the user or system administrator, and checked against the behavior that the widget declares itself to have (via config.xml).

The default security model for widgets can be summarized as follows:

A user agent must silently deny direct access to resources residing on a user’s file system.
A use agent must allow a widget to access content over the widget protocol.
A user agent must deny access to the end-user's file system over the file: URI scheme.
In the presence of a protocol element, a user agent should grant a widget access protocols supported by the user agent through the appropriate URI scheme (e.g., ftp, etc.). In the absence of protocol elements, user agent MUST allow a widget to access content over the http and https protocols.
A user agent must allow communication over default ports, or only to the ports the author has pre-declared ports using the port element. A user agent, however, must deny widgets from using ports equal to or below 1023 that are not default ports, even if access is requested by the author via the port element.

5.1 Network classes

This specification describes two classes of networks: a private network, and a public network.

A private network, or local network is by default defined as the user's local machine, including any IP address that resolves to the local machine. Further, the IP ranges as defined by [RFC 1918], are considered to be private. These addresses are primarily being used in systems set up behind a NAT translation device, and provides machines with unique addresses where there is only one public IP address for several machines. These addresses are:

     10.0.0.0        -   10.255.255.255  (10/8 prefix)
     172.16.0.0      -   172.31.255.255  (172.16/12 prefix)
     192.168.0.0     -   192.168.255.255 (192.168/16 prefix)

In addition, when a user is within an ad-hoc network, networking equipment (including software components in operating systems), typically use the IPv4 Link-Local addresses as defined by [RFC 3927], which is also considered to be part of the local network.

    169.254.0.0     -    169.254.255.255 (169.254/16 prefix)

The user agent must provide a default configuration wherein the four network ranges described above are defined to fall within the private IP range. This policy should be editable by the user, meaning it should be possible to add or remove items to the list of private networks and hosts.

A public network is any IP range outside the definition of a private network.

5.2 Security example

The following example contains a security element 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 does not want access to plugins.

<widget ...>
 <security>
  <access>
    <host>example.com</host>
    <host>example.org</host>
    <path>/good</path>
    <port>2048-4906</port>
    <port>80,1337</port>
  </access>
  <content plugins="no"/>
</security>
</widget>

5.3 The widget: URL protocol

A widget:// protocol URL is defined as below

  widget_protocol_url = "widget://" widget_identifier "/" [path] ["?" query] ["#" fragment];
  widget_identifier = [a-z0-9]+

The path component is optional, and follows the the definition given for the path component in section 3.3 of rfc3986. Likewise, query strings and fragments are permitted, as defined by sections 3.4 and 3.5 of same document. The path always refers to the root of the widget folder, and traversing beyond this is not allowed.

Example: If we have a widget with the identifier decafbad, and we want to reference a file ‘caffeine.xml’, placed in the widget's root folder, for inclusion, we would refer to this URL:

widget://decafbad/caffeine.xml

The widget_identifier SHOULD be unique, and semi-randomly generated. Two different widget installations on a system MUST NOT share the same widget identifier.

5.3.1 Access rules

Any access to URLs in the widget:// URL space is bound by a strict same-origin policy, meaning that a resource defined by a widget: URL cannot be accessed in another context than the widget wherein the widget is contained.

External resources loaded in the widget, through iframes, svg:foreignObject and similar mechanisms MUST NOT be allowed to access resources[1] inside the widget, or to utilize the widget:// URL space.

If a widget embeds a file from within the widget, by means of frames or similar mechanisms, the embedded documents MUST be running in the context of the widget, and will be subject to the same security restrictions as the widget.

It SHOULD NOT be possible to launch one widget from within another widget.

It MUST NOT be possible to access the widget: URI space from other browsing contexts than inside the widget, or a window that can be determined to be completely trusted and running with extended security privileges. This means that a strict same-origin policy exists between different widgets.

Objects included in the widget from a source outside the widget cannot access documents using the widget:// protocol. This means that if a widget includes an iframe to http://example.com/, the document on example.com is not able to access URLs using the widget:// protocol.

5.4 Widget instances

Separate widget instances share no information at all. Specifically:

A cookie set by a widget instance, or by a URL loaded by a widget (e.g. through XmlHttpRequest) is visible only to that widget instance, never to any other instances or to documents loaded into the use agent in any other way.
If a URL loaded by a widget requires HTTP authentication then authentication must be performed on behalf of that widget instance; the authentication is not shared with other widget instances or with URLs loaded into the user agent in any other way.
A set of settings for a widget instance is shared with no other widget instances.
Other persistent storage mechanisms, such as those defined in HTML must not share data with other widget instances, or with the storage context in the user agent.
Cache files or cache indexes are not shared with the user agent, or with any other widget instance
Widget cache data should not be indexed in the user agent's history search engine.

5.5 Form and Links Behavior

The security model defines the following behavior for forms and links; thus ensuring forms and links do not violate security policy:

A form element should have a valid target.
If the form has a reserved target, and this target leads to intrinsically replacing the topmost document in the widget, in effect replacing the widget, submitting the form should fail silently.
If the form uses the ‘_blank’ target for a GET request, the form should be submitted to an external application (in effect, the user agent's main user agent instance.
POST requests that result in submission to an external viewer SHOULD fail.
The URL provided by the form's action attribute MUST be permitted by the computed security policy for the widget.
Links must have default "_blank" target, and open in an external viewer. The URL referenced MUST be permitted by the computed security policy for the widget.

5.6 Embedded object security context

The security model defines the security context and behavior for embedded objects:

Objects must adhere to widget security policy.
Objects must not cross network boundaries when loaded.
Objects may share cookies and cache with widgets.
Objects must not share cookies and cache with user agent.
Objects must not be aware of widget's existence.
- There should be no reference to window.opener (the widget shouldn't be visible to the object).
- window.top should point to the embedding frame only.
Widgets may have a one-way reference to inject scripts, read DOM, etc. The reference must be strictly one way and initiated from the widget only.

5.7 Symbolic links

If a widget package file contains symbolic links, leading either to a target in- or outside the widget, the symbolic link must not be made available to the instantiated widget: In other words, the symlink MUST NOT be followed by the user agent.

In the event that the widget package, when unpacked on a device, contains a hard link, the user agent must never create the hard link on disk.

6 Widget modes

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

widget: The widget mode describes traditional desktop widgets, applications that are displayed without application chrome such as resizing controls or title bars. Widgets displaying in this mode are expected to be in control of their own rendering environment, meaning they can set or reset their size at will. On targets where the widget does not fit, the platform is expected to provide a scrolling mechanism or other means of navigating around the widget, while allowing the widget to be rendered and displayed according to the geometry information the widget has available.
application: The application mode typically describes widgets that on a system with window management, will display chrome and controls for moving, or resizing the widget. Widgets in this mode are expected to have the window/widget size controlled by the end-user or operating environment, but the widget may suggest initial layout information.
fullscreen: This mode is equal to the application mode, except that the initial default size provided by the runtime environment is expected to be full screen, or what equates a ‘maximized’ mode for desktop application.
docked: The dock mode, sometimes referred to as ‘microwidget mode’, is a mode wherein the widget typically renders and displays in a minimized state, such as an idle screen, list view, or other types of display where the widget has more limited size. Typically, widgets in this mode are not expected to be interactive, and the user can only interact with the widget through activating it, and thus switch it into one of the previously defined modes.

6.1 CSS extensions for widget modes

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 widget modes as the value to specify the styling.

6.1.1 Examples

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";
  }
}

7 Widget scripting interfaces

7.1 The widget object

The purpose of the widget object is to expose functionality specific to widgets.

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 management; */
         attribute Function onshow;
         attribute Function onhide;
    void show();
    void hide();


}

7.2 The `identifier` attribute

The identifier attribute represents a universally unique identifier of the widget instance. Upon getting, the user agent must return a string.

7.3 The `originURL` attribute

The origin from which the widget was acquired. The value of this attribute is an IRI, or null. Upon getting, the user agent must return a URI as string that is %-decoded representing the URI from which the widget was acquired, or null if the acquisition origin is unknown.

7.4 The `widgetMode` attribute

The widgetMode attribute identifies the current rendering mode for the widget.

Upon getting, the user agent should return one of the values widget, application, fullscreen or docked.

7.5 The `openURL`() method

The openURL() method on the widget object takes URI as an argument, as defined by [RFC3987]. When this method is called with a valid URI, the user agent URL should open the URI with the appropriate scheme handler (e.g., "tel:+12345422" might be opened with a telephony application).

Note that restrictions to what URLs can be opened using openURL, as defined in the security section of this specification:

Widgets cannot open URLs using the file: scheme.
OpenURL does not accept relative IRI’s and as such cannot open any files element stored inside the widget.

7.6 The `preferenceForKey()`

The preferenceForKey() method takes a String argument, key. When called, the user agent must return a string that has previously been stored with the setPreferenceForKey method, or undefined if the key does not exist.

7.7 The `setPreferenceForKey()` method

The setPreferenceForKey() method takes two String arguments, preference and key. When called, the user agent must persistently store the value of preference and key. However, if called and the value of key is null and the key argument has been previously stored, the user agent must delete the key and preference from the storage area.

7.8 The `getAttention`() method

This method serves to bring the widget to the user's attention.

A user agent should use platform specific means/conventions to bring the widget to the user's attention, but should not grab the window focus.

Methods of bringing the user's attention to the widget, can, for instance,

7.9 The `showNotification`() method

The showNotification() method takes two arguments, the first being a String with the message text, and a second argument being a function that serves 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 new lines is significant.

Upon the user acknowledging the notification, the callback function is called without any arguments.

7.10 The `onshow` attribute

When 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.

7.11 The `onhide` attribute

When 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.

7.12 The `show`() method

The 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.

7.13 The `hide`() method

The 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 hide will perform no action.

7.14 The `widgetWindow` interface

A widget's initial dimensions are controlled by the width and height elements in the widget configuration document. In addition to this, a widget can be resized dynamically using Javascript, with 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);
  }

7.14.1 The `status` attribute

The 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.

7.14.2 The `defaultStatus` attribute

The defaultStatus attribute, when set provides a default status message which is to be displayed in a widget management 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.

7.14.3 The `moveTo`() method

When 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.

7.14.4 The `moveBy`() method

When 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.

7.14.5 The `resizeTo`() method

When 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 widget configuration document 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

7.14.6 The `resizeBy`() method

The 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 widget configuration document 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.

7.14.7 Storing geometry information

When a successful resize of the widget has been performed using any of the four mentioned, the resulting values should be stored, and used in place of any values specified in the widget configuration document.

7.15 The `WidgetModeChangeEvent` interface

When 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 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,
}

7.16 The `ResolutionEvent` interface

The 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);
}

8 Widget autodiscovery

8.1 Purpose

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.

8.2 Definition

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"
/>

8.3 Relationship to HTML and XHTML

8.3.1 Syntax rules inherited from HTML and XHTML

When a widget autodiscovery element appears in a [HTML401] or [XHTML10] document, the element shares all the syntax rules and restrictions of other markup elements.

8.3.2 Multiple autodiscovery elements

A document may contain multiple autodiscovery elements. A User Agent should present an installation option for all auto discovered widgets to the user, listed in the order of appearance in the source code.

A User Agent that only presents one auto discovered widget to the user should choose the first auto discovered widget for installation whenever the user opts to install the widget.

8.4 Required attributes

8.4.1 The `type` attribute

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.

8.4.2 The `rel` attribute

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, lowercase, or mixed case.

8.4.3 The `href` attribute

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].

8.5 Optional attributes

8.5.1 The title attribute

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.

Acknowledgements

The specification for the widget object builds on Apple’s [Dashboard] reference.

Widget Autodiscovery in large parts builds on the [AtomAutodiscovery] specification.

References

[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997. RFC2119 is available at http://www.ietf.org/rfc/rfc2119
[ZIP]: .ZIP File Format Specification. PKWare Inc., January 2006 The .ZIP File Format Specification is available at http://www.pkware.com/business_and_developers/developer/popups/appnote.txt
[XML10]: Extensible Markup Language (XML) 1.0 (Third Edition). Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau. W3C, February 2004. Extensible Markup Language (XML) 1.0 specifciation is available at http://www.w3.org/TR/REC-xml/
[CSS21]: Cascading Style Sheets, level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006. The CSS 2.1 Specification can be found at http://www.w3.org/TR/CSS21/
[RFC3987]: Internationalized Resource Identifiers (IRIs) . M. Duerst, M. Suignard. IETF, January 2005. RFC3987 is available at http://www.ietf.org/rfc/rfc3987
[Dashboard]: Dashboard Reference. Apple Computer, Inc, May 2006. The Apple Dashboard Reference is available at http://developer.apple.com/documentation/AppleApplications/Reference/Dashboard_Ref/index.html
[HTML401]: HTML 4.01 Specification, Dave Raggett, Arnaud Le Hors, Ian Jacobs. W3C, December 1999. The HTML 4.01 Specification is available at http://www.w3.org/TR/html401/
[XHTML1]: XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition), S. Pemberton et al. W3C, January 2000. The XHTML 1.0 specification is available at http://www.w3.org/TR/xhtml1/
[AtomAutodiscovery]: Atom Autodiscovery (draft), M. Pilgrim, P. Ringnalda. ATOMPUB Working Group, May 2005-. The Atom Autodiscovery specification draft is available at http://philringnalda.com/rfc/draft-ietf-atompub-autodiscovery-01.html
[SVG]: Scalable Vector Graphics (SVG) 1.1 Specification, Jon Ferraiolo, FUJISAWA Jun, Dean Jackson. W3C. The SVG 1.1 specification is available at http://www.w3.org/TR/SVG/
[DOM3Core]: Document Object Model (DOM) Level 3 Core Specification. A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. World Wide Web Consortium, April 2004.

Appendix A: Widget positioning and sizing

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

8.6 Algorithm for widget sizing

The following algorithm is used for determining the start size of a widget.

The widget configuration document is opened
Read the ‘defaultmode’ attribute of the widget element in the widget configuration document
If the widget has been started in the past, and the defaultmode value is ‘widget’, read the stored ‘start width’ and ‘start height’ values, and go to step 11
If the widget has been started in the past, and the defaultmode is ‘application’, and the value of ‘start width’ exceeds the available rendering surface width (In other words, when the geometry of the rendering surface has changed), let the ‘start width’ be equal to the available rendering surface width, and continue to the next step.
If the widget has been started in the past, and the defaultmode is ‘application’, and the value of ‘start height’ exceeds the available rendering surface height (In other words, when the geometry of the rendering surface has changed), let the ‘start width’ be equal to the available rendering surface width, and continue to step 11.
If the value for defaultmode is ‘fullscreen’, and the widget supports the concept of fullscreen/maximized applications, let the ‘start width’ and ‘start height’ values be determined by the maximum available rendering surface width and height, and go to step 11.
If the value for defaultmode is ‘fullscreen’, and the runtime does not support the ‘fullscreen’ mode, but supports the ‘application’ mode, assume that the defaultmode is ‘application’, go to step 8.
If the value for defaultmode is ‘application’, and the runtime does not support the ‘application’ mode, but supports ‘fullscreen’, assume that the defaultmode is set to ‘fullscreen’, and go to step 5.
If the value for defaultmode is ‘application’ and the platform supports the mode, and allows widgets to set their own size:
1. Read the ‘width’ element from widget configuration document. If this value is less than the maximum available width, store this value as ‘start width’.
2. If the ‘width’ value is larger than the available width, allocate the largest available width, and store it in ‘start width’.
3. Read the ‘height’ element from widget configuration document. If this value is less than the maximum available height, store this value as ‘start width’.
4. If the ‘height’ value is larger than the available height, allocate the largest available height, and store it in ‘start height’.
5. Continue to step 11
If the value for defaultmode is one of ‘application’ or ‘fullscreen’, and neither mode is supported by the widget runtime, assume that the value is ‘widget’, and continue to step 10
If the application mode is ‘widget’ and the mode is supported by the runtime, use the values of the ‘width’ and ‘height’ element as values for ‘start width’ and ‘start height’, respectively, and go to step 10.
Determine the initial widget position as described in the algorithm below. Create a widget window using the widths ‘start width’ and ‘start height’ as described as the initial start width and height. and start the widget. Store the ‘start width’ and ‘start height’ values permanently.

8.7 Determining the initial widget position

Use the following algorithm to determine the initial widget position

If the widget has been started before, go to step 4.
Let the initial rendering position of the widget be determined by the upper left corner, using the values ‘start_x’ and ‘start_y’
If the widget has the defaultmode ‘widget’, determine the initial position as thus:
1. Read the assumed ‘start width’ value as determined in the sizing algorithm. If the width of ‘start width’ is equal to, or larger than the width available to the widget, let the widget's upper left start position, ‘start x’, be 0, and continue to step 3.3.
2. If the assumed ‘start width’ value is less than the available width, let the value ‘start_x’ be calculated according to the following formula: start_x = (available width-start width)/2. Otherwise, let the start_x value be 0.
3. Read the assumed ‘start height’ value as determined in the sizing algorithm, and continue.
4. If the assumed ‘start height’ value is less than the available height, let the value ‘start_y’ be calculated according to the following formula: start_y = (available height-start height)/2. Otherwise, let the start_y value be 0.
Position the widget according to the start_x and start_y values, and display the widget.

8.8 Other

These are implementation guides for resizing, positioning and widget types, this algorithm is considered informative.

On window managers that support window states like ‘maximized’ and ‘restored/unmaximized’, assume that the ‘fullscreen’ mode equals the ‘maximized’ mode, and that ‘application’ equals ‘restored/unmaximized’ mode.
When a widget is moved or resized using windows.move(To|By), and windows.resize(To|By), use the new values for widget size and position as determined after these method calls as new values for ‘start width’, ‘start height’, ‘start_x’, and ‘start_y’. These values should be stored and used when a widget is started again.
The widget's own dimensions must be respected for widgets rendering using the ‘widget’ rendering mode.
When the widget is an application or fullscreen widget, the widget runtime may ignore calculated positioning and sizing information.

8.9 Virtual viewport resizing

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 work alike must be implemented to facilitate a good user experience.

Relation to the width element

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:

If the window manager does not allow chromeless windows to be dragged off the desktop, the user agent may resize the window according to the following algorithm:
1. Scan the leftmost vertical line of the widget. If this line only conta/spanins transparent pixels, decrease width by one.
2. Scan the rightmost vertical line of the widget. If this line only contains transparent pixels, decrease width by one.
3. Repeat 1) and 2) until the first non-transparent pixel is found.
The recalculated window width must not, under any circumstance cause visible pixels to be clipped from the widget.

Relation to the height element

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:

If the window manager does not allow chromeless windows to be dragged off the desktop, the user agent may resize the window according to the following algorithm:
1. Scan the topmost horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
2. Scan the bottom horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
3. Repeat 1) and 2) until the first non-transparent pixel is found
The recalculated window height must not, under any circumstance cause visible pixels to be clipped from the widget.

Opera Widgets SDK table of contents

Chris Mills

Chris Mills is a web technologist, open standards evangelist and education agitator, currently working at Opera Software in the developer relations team. He spends most of his time writing articles about web standards for dev.opera.com and other publications (such as .net mag and A List Apart), giving talks at universities and industry conferences, and lobbying universities to improve their web education courses. He believes that education is the answer to everything, but in particular he is passionate about using education to improve the overall content quality, accessibility, usability and future-viability of the Web.

He is the creator of the Opera Web standards curriculum, contributor to the WaSP InterACT project, and coauthor of InterACT with web standards: A Holistic Approach to Web Design. In August 2011, he also accepted the position of co-chair of the newly-formed Web Education Community Group.

Outside work he is a heavy metal drummer, proud father of three and lover of good beer.

This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.

Opera Widgets specification 1.0, fourth edition

This article is deprecated

Abstract

Opera Software Specification

Abstract

Scope of this Document

Table of contents

1 Introduction

1.1 Conformance Requirements

2 Opera widget package

2.1 Widget folder structure

2.2 Content type

2.3 File extension

3 Widget configuration document

3.1 White space

4 Elements of the widget configuration document

4.1 The widget element

4.2 The widgetname element

4.3 The width element

4.4 The height element

4.5 The widgetfile element

4.6 The author element

4.7 The description element

4.8 The icon element

4.9 The feature element

4.10 The param element

4.11 The id element

4.12 The security element

4.13 The access element

4.14 The content element

5 Security model

5.1 Network classes

5.2 Security example

5.3 The widget: URL protocol

5.3.1 Access rules

5.4 Widget instances

5.5 Form and Links Behavior

5.6 Embedded object security context

5.7 Symbolic links

6 Widget modes

6.1 CSS extensions for widget modes

6.1.1 Examples

7 Widget scripting interfaces

7.1 The widget object

7.2 The identifier attribute

7.3 The originURL attribute

7.4 The widgetMode attribute

7.5 The openURL() method

7.6 The preferenceForKey()

7.7 The setPreferenceForKey() method

7.8 The getAttention() method

7.9 The showNotification() method

7.10 The onshow attribute

7.11 The onhide attribute

7.12 The show() method

7.13 The hide() method

7.14 The widgetWindow interface

7.14.1 The status attribute

7.14.2 The defaultStatus attribute

7.14.3 The moveTo() method

7.14.4 The moveBy() method

7.14.5 The resizeTo() method

7.14.6 The resizeBy() method

7.14.7 Storing geometry information

7.15 The WidgetModeChangeEvent interface

7.16 The ResolutionEvent interface

8 Widget autodiscovery

8.1 Purpose

8.2 Definition

8.3 Relationship to HTML and XHTML

8.3.1 Syntax rules inherited from HTML and XHTML

8.3.2 Multiple autodiscovery elements

8.4 Required attributes

8.4.1 The type attribute

8.4.2 The rel attribute

8.4.3 The href attribute

8.5 Optional attributes

8.5.1 The title attribute

Acknowledgements

References

4.1 The `widget` element

4.2 The `widgetname` element

4.3 The `width` element

4.4 The `height` element

4.5 The `widgetfile` element

4.6 The `author` element

4.7 The `description` element

4.8 The `icon` element

4.9 The `feature` element

4.10 The `param` element

4.11 The `id` element

4.12 The `security` element

4.13 The `access` element

4.14 The `content` element

7.2 The `identifier` attribute

7.3 The `originURL` attribute

7.4 The `widgetMode` attribute

7.5 The `openURL`() method

7.6 The `preferenceForKey()`

7.7 The `setPreferenceForKey()` method

7.8 The `getAttention`() method

7.9 The `showNotification`() method

7.10 The `onshow` attribute

7.11 The `onhide` attribute

7.12 The `show`() method

7.13 The `hide`() method

7.14 The `widgetWindow` interface

7.14.1 The `status` attribute

7.14.2 The `defaultStatus` attribute

7.14.3 The `moveTo`() method

7.14.4 The `moveBy`() method

7.14.5 The `resizeTo`() method

7.14.6 The `resizeBy`() method

7.15 The `WidgetModeChangeEvent` interface

7.16 The `ResolutionEvent` interface

8.4.1 The `type` attribute

8.4.2 The `rel` attribute

8.4.3 The `href` attribute