Opera Widgets Specification 1.0

By Opera Software

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

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 attribute

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

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

1. Widgets do not have access to content residing on a user’s file system, using the file: protocol
2. 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.
3. Widgets may access content over https, but only if the widget has declared this in the security section of config.xml
4. 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.
5. 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.