Opera: Widgets support in Opera Presto 2.3

Widgets support in Opera Presto 2.3

Opera supports the following terms of the Opera Widgets Specification 1.0 fourth edition. For further reference, please see: Opera Widgets Specification 1.0 fourth edition.

In this page:: Widget configuration document: elements, attributes, and values; Widget security model; Widget modes; Widget scripting interfaces; Widget autodiscovery

Widget configuration document: elements, attributes, and values

Opera provides support for the following items.

Elements, attributes and values support
Element	Attribute(s)	Value(s)	Description	Support
`<widget>`			Root element of a Widget configuration document	Yes
	`defaultmode`		Represents the preferred Widget mode for a Widget.	Yes
		`"widget"`	Typically rendered by Opera without user chrome; the Widget has control over its own window size.	Yes
		`"application"`	The Widget is assumed to be rendered in a viewport size determined by Opera.	Yes
		`"fullscreen"`	The Widget is expected to be rendered using the entire available viewport.	Yes
	`dockable`		Specifies whether the Widget supports docking where a Web document is displayed.	Yes
		`"yes" "true" "dockable"`	All other values are interpreted by Opera as the value `"false"`, meaning that the Widget does not provide a docked mode.	Yes
	`transparent`		Employed to control the Widget's use of background transparency.	Yes
		`"yes" "true" "transparent"`	Opera interprets all other values as `"false"`, meaning that Opera does not make the Widget's background transparent.	Yes
	`network`		Optional. Allows an author to declare their intention to access the public network and/or private networks. It takes a space-separated list of values.	Yes
		`"private" "public" "public private" "private public"`	- Widget only requires access to the private network. - Widget only requires access to the public network. - Widget requires access to both public networks and/or private networks.	Yes
`<widgetname>`			Contains a string whose purpose is to provide a human-readable title for the Widget.	Yes
`<width>`			A value in CSS pixels, as per section 4.3.2 of CSS2.1, that represents a Widget's drawable area along the horizontal axis.	Yes
		`"integer" (0-9) or "300"`	After whitespace normalization, a Opera interprets the resulting value as an integer (a string that only contains the characters [0-9]). If the attribute is missing, or its value is invalid, then Opera uses the value "300".	Yes
`<height>`			A value in CSS pixels, as per section 4.3.2 of CSS2.1, that represents a Widget's drawable area along the vertical axis	Yes
		`"integer" (0-9) or "300"`	After whitespace normalization, a Opera interprets the resulting value as an integer (a string that only contains the characters [0-9]). If the attribute is missing, or its value is invalid, then Opera uses the value "300".	Yes
`<widgetfile>`			Points the Widget to a start file for the Widget.	Yes
`<author>`			Optional. A container element for metadata about the Widget's author. This element can contain the following child elements: `<name>`: Optional. Represents the name, or names, of the author of the Widget. `<organization>`: Optional. Represents the name of an organization that the author is affiliated with. `<email>`: Optional. Represents an e-mail address for the author of the Widget. `<link>`: Optional. Represents an IRI which the author associates with him or her self.	Yes
`<description>`			A short plain-text description of the Widget.	Yes
`<icon>`			A path to an icon file contained within the Opera Widget package that Opera can display to the end user in appropriate contexts.	Yes
	`width` `height`	`"integer" "integer"`	Optional. The value of `width` is an unsigned integer, representing the desired width of the icon in device pixels. Optional. The value of height is an unsigned integer, representing the desired height of the icon in device pixels.	Yes
`<feature>`			Optional. A runtime component or functionality beyond the default set of functionality that Opera provides to a Widget at runtime (e.g., the file IO API).	Yes
	`name required`	`"feature" "true" "false"`	The name of a feature, as represented by a URI. Optional. Indicates to Opera if the feature is required for correct operation of the Widget.	Yes
`<param>`			Optional. Allows declaration of parameters, which may be associated and used by `<feature>`.	Yes
	`name` `value`		A string representing the parameter name. A string representing the parameter value.	Yes
`<id>`			Optional. Establishes an identity for a Widget. When used, must contain one of each of the following child elements, in any order: `<host>`: A fully qualified domain name that identifies the host from which the Widget can be downloaded. `<name>`: A string that is unique to the domain specified in the host element. `<revised>`: A string in the [W3CDTF] format.	Yes
`<security>`			Optional. 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. When used, an author must use one of the following child elements: `<access>` `<content>`	Yes
`<access>`			A container element whose child elements declare which protocols, hosts, ports, and paths the Widget can use. Child elements are: `<protocol>` `<host>` `<port>` `<path>`	Yes
`<content>`			Allows authors to disable support for plug-ins within their Widgets.	Yes
	`plugin`		Enables the Widget to use `plugin` as embedded content (e.g., a Flash file).	Yes
		`"yes" "no" "true" "false" "plugin"`	All other values, included disallowed values, means that the Widget will not use `plugin` as embedded content.	Yes

Widget security model

Opera supports the default Widgets security model. The following points are a summary of the Opera default security model for Widgets.

Opera silently denies direct access to resources residing on a user's file system.
Opera allows a Widget to access content over the Widget protocol.
Opera denies access to the end-user's file system over the file: URI scheme.
In the presence of a protocol element, Opera grants a Widget access to protocols that it supports through the appropriate URI scheme (e.g., ftp, etc.). In the absence of protocol elements, Opera allows a Widget to access content over the http and https protocols.
Opera allows communication over default ports, or only to the ports the author has pre-declared as ports using the port element. Opera, however, denies 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.

Network classes

There are two classes of networks: a private network, and a public network.

Private 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)

Public network

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

Security example

The following code example indicates that the Widget should be allowed to contact the domains example.com and example.org, 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 plug-ins.

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

The widget: URL protocol

Opera supports the widget:// protocol URL. This is defined in the following code example.

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

Access rules

Opera supports the following 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:foreignObjectand similar mechanisms are not 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.
Opera prevents launching one Widget from within another Widget.
Opera prevents access to 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.

Widget instances

Opera specifies that separate Widget instances share no information at all.

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 Opera 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 do not share data with other Widget instances, or with the storage context in Opera.
Cache files or cache indexes are not shared with Opera, or with any other Widget instance.
Widget cache data should not be indexed in the Opera's history search engine.

Form and Links Behavior

The Opera Widgets security model defines the following behavior for forms and links, and ensures 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.
POST requests that result in submission to an external viewer SHOULD fail.
The URL provided by the form's action attribute is 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.

Embedded object security context

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

Opera specifies that:
- 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 Opera.
- Objects must not be aware of a Widget's existence.
- There should be no reference to window.opener (the Widget should not 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.

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, Opera does not follow the symlink.

In the event that the Widget package when unpacked on a device contains a hard link, Opera will never create the hard link on disk.

Widget modes

Opera supports Widget modes. Widgets can be displayed in several different contexts or modes. An installed Widget may support several of following the modes.

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 to a "maximized" mode for desktop application.
docked: The docked 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.

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. Opera supports the following 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%; }
}

Not specifying a value:

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

Widget scripting interfaces

Opera supports the Widget scripting interfaces. 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();

}

identifier attribute

Represents a universally unique identifier of the Widget instance. Upon getting, Opera returns a string.

originURL attribute

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

widgetMode attribute

Identifies the current rendering mode for the Widget. Upon getting, Opera returns one of the values: widget, application, fullscreen or docked.

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, Opera opens 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 IRIs and as such cannot open any files stored inside the Widget.

preferenceForKey() method

Takes a String argument, key. When called, Opera returns a string that has previously been stored with the setPreferenceForKey method, or undefined if the key does not exist.

setPreferenceForKey() method

Takes two String arguments, preference and key. When called, Opera persistently stores the value of preference and key. However, if called and the value of key is null and the key argument has been previously stored, Opera deletes the key and preference from the storage area.

getAttention() method

Brings the Widget to the user's attention. Opera uses platform specific means/conventions to bring the Widget to the user's attention, but should not grab the window focus.

showNotification() method

Takes two arguments:

a String with the message text
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.

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.

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.

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() 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.

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 following extensions.

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: 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: 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 an empty string, the Widget runtime should fall back to a system-provided message.
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.
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, with the integer values delta_pos_x and delta_pos_y being 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() 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 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.
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 additions must produce exactly the same dimensions 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 1x1 pixel, in which case the resizeBy() method should result in no change to the Widget size.
Storing geometry information: When a successful resize of the Widget has been performed using any of the above mentioned items, the resulting values should be stored, and used in place of any values specified in the Widget configuration document.

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

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 newly available width and height attributes 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);
}

Widget autodiscovery

Opera supports Widget autodiscovery.

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. Opera, as a Widget-aware Web client offers a mechanism that exposes the presence of the Widget to the user, and offers a mechanism for installing the Widget.

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

Relationship to HTML and XHTML

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.
Multiple autodiscovery elements: A document may contain multiple <autodiscovery> elements. Opera presents an installation option for all auto discovered Widgets to the user, listed in the order of appearance in the source code. If Opera only presents one auto discovered Widget to the user, Opera chooses the first auto discovered Widget for installation whenever the user opts to install the Widget.

Required attributes

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.
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.
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].
title attribute: May be present in a Widget <autodiscovery> element. Opera treats the value of the title attribute as a human-readable title for the Widget, and Opera presents this title to the user.