Opera Widgets Specification 1.0
14th December 2011: This article is obsolete
This article is obsolete/out of date, so should no longer be treated as a current or reliable source of information. This is an old version of the Opera Widgets specification 1.0, so unless you have a really specific reason to read this one, you should read the Opera Widgets Specification 1.0 Fourth Edition instead.
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.
Table of contents
- Introduction
- Widget packaging
- Widget configuration file: config.xml
- Widget JavaScript interfaces
- Widget autodiscovery
- Acknowledgements
- References
Introduction
Conformance Requirements
The keywords ”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].
Widget packaging
File format
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.
Widget files
Every Opera Widget must contain the following two files:
- config.xml – a manifest
file containing information necessary to initialize the widget. This
file always contains information about the widget’s name and geometry,
and may optionally contain more information about the widget:
- Widget description
- Author information
- Icon reference
- Security information
- index.html – this is the main document for the actual widget, and is displayed in a viewport established by the config.xml file. This HTML document can reference external content, including, but not limited to scripts, CSS files and images the same way regular web pages can.
Widget folder structure
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.
Content-Type
When widgets are served from web servers, they must be served with the content-type application/x-opera-widgets
.
File extension
Widgets must have the file extension .zip to be properly recognized as widgets.
Widget configuration file: config.xml
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.
White space
When presented to the end user, whitespace characters in config.xml elements are normalized the following way:
- Leading and trailing whitespace is stripped
- Multiple whitespace are normalized to single whitespace characters.
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.
The widget
element
The 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].
Required child elements of widget
The widgetname
element
The 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.
The width
element
The 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]
The height
element
The 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]
Optional child elements of widget
The author
element
The 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.
The name
element
If 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.
The organization
element
If 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.
The email
element
If 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.
The link
element
If 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.
The description
element
The 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.
The icon
element
The 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].
The security
element
The 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.
The access
element
The 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.
protocol
The protocols the widget will be using to contact external servers. All protocols, except the file protocol is permitted.
host
The
host
element establishes which hostnames may be contacted. The hostnames 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.port
The
port
element establishes which port numbers the widget will be using. The value is either a number, a range of numbers separated by a dash, e.g.1024–2048
, or a comma-separated list of ports, e.g.80, 1337
.path
The
path
element specifies the path part of the URI a widget may contact.
The content
element
Widgets 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”.
Security model
The widget access model is summarised as follows.
- Widgets do not have access to content residing on a user’s file system, using the file: protocol
- Widgets may access content over http, regardless over the presence of a security section in config.xml. Widgets may not use any other protocol without prior declaration.
- Widgets may access content over https, but only if the widget has declared this in the security section of config.xml
- Widgets can not access both hosts on intranets and Internet. If a widget has contacted address defined as an intranet, it may no longer contact an address not defined as an intranet address. Likewise, if a widget contacts something defined as not being an intranet, it may no longer contact intranet addresses.
- Widgets may not contact non-default ports, except when pre-declared in config.xml. Further, widgets may not contact non-default ports equal to or below 1023.
Intranet definition
An intranet is defined based on the resolved IPv4 address of a host name. The following IPv4 ranges are defined as intranets:
- 10.0.0.0 to 10.255.255.255
- 172.16.0.0 to 172.31.255.255
- 192.168.0.0 to 192.168.255.255
- 169.254.0.0 to 169.254.255.255
All other IP ranges than these are defined as Internet addresses.
Security example
The following example contains a security section would indicate that the widget should be allowed to contact the domains example.com
and example.org
using either the https or http protocols, but only to the path ’/good’ on ports 80,1337 and ports in the range 2048–4096. In addition, the widget wants access to Java, but not plugins.
<security>
<access>
<protocol>http</protocol>
<protocol>https</protocol>
<host>example.com</host>
<host>example.org</host>
<path>/good</path>
<port>2048-4906</port>
<port>80,1337</port>
</access>
<content java="yes" plugins="no" />
</security>
The id
element
The id
element is an optional child element of the widget
element. If present, this element may be used to establish a concept of identity of the widget that may be used for recognizing version updates and similar. The syntax requirement for this element is to have three required child elements, containing strings, as specified below.
host
This element is required, and must be a fully qualified domain name naming the host from which the widget was downloaded.
name
This element is required, and must be a string that is unique to the domain specified in the
host
element.revised
This element is required, and must be a string in the [W3CDTF]:#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.
Widget JavaScript interfaces
The widget object
Purpose
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
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:
- Widgets cannot open URLs in the
file:
domain - Widgets that have contacted the non-routable IPv4 address ranges as specified cannot use openURL to open URLs in other IPv4 ranges than those specified
- Likewise, widgets that have contacted addresses outside the four non-routable address, cannot use openURL to open URLs in the specified ranges.
- OpenURL does not accept relative IRI‘s and as such cannot open any files stored inside the widget.
The preferenceForKey() method
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
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.
Widget geometry
A widget’s initial dimensions are controlled by the width
andwidth
elements of the config.xml file.
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. 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.
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 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 restricitions of other markup elements.
Multiple autodiscovery 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.
Required attributes
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.
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, lowecase, or mixed case.
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].
Optional attributes
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
This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.
Comments
The forum archive of this article is still available on My Opera.