This document describes Opera Widgets, and covers all aspects of Opera Widgets from packaging format, the manifest file config.xml, and JavaScript interfaces for working with widgets.
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].
Widgets are 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 the widgets in a directory inside the zip file, with all the widget’s files and folders located inside this subfolder. This folder should bear the same name as the compressed zip file.
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 must have the file extension .zip to be properly recognized as widgets.
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×300px (CSS pixels):
<widget>
<widgetname>
Hello World!
</widgetname>
<width>
300
</width>
<height>
300
</height>
</widget>
The widget may optionally contain an XML prolog.
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>widgetname elementThe widgetname element must be present in config.xml as a child of the widget
element, and is 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 must 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]
height elementThe height element must 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]
h3(#xml-optional-elements) Optional child elements of <widget>
author elementThe author element is an optional 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 author 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 author 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 author 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 author 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] or [GIF89].
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 subelements are interpreted to mean “any”. 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.
protocolThe protocols the widget will be using to contact external servers. All protocols, except the file protocol is permitted.
hostThe host element establishes which hostnames may be contacted. The hostnames is an exact match, so a widget specifying www.example.com must not be able to contact example.com. IP addresses may also be used as values.
portThe 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.
pathThe 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</path>
<port>80,1337</path>
</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.
hostThis element is required, and _must_ be a fully qualified domain name naming the host from which the widget was downloaded.
nameThis element is required, and _must_ be a string that is unique to the domain specified in the host element.
revisedThis element is required, and _must_ be a string in the [W3CDTF]:#refsW3CDTF 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.
The purpose of the widget object is to expose
functionality specialized to widgets that should not or must not be
available or to to scripts running on regular web pages. The widget
object implements the Widget interface:
interface Widget {
void <a href="#wo-openURL">openURL</a>(String URL);
String <a href="#wo-preferenceForKey">preferenceForKey</a>(String key);
void <a href="#wo-setPreferenceForKey">setPreferenceForKey</a>(String value,
String key);
}
The openURL() method on the widget object takes a String an argument. Further, this string must be a valid 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.
The openURL() method on the widget object takes a String an argument. Further, this string must be a valid 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:
The 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.
The setPreferenceForKey() method takes two String arguments, preference and key. When called, this methods stores the string in the preference argument, and stores it with the key named 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 deletec in the key argument.
A widget’s initial dimensions are controlled by the width andwidth elements of the config.xml file.
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 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.