Widget包的格式内容（Widget Package Format ）

Widget Resources

Zip archives

Widget package is a zip archive that conforms to Zip File Format Specification. Widget package in ZIP format is named with a suffix of '.wgt'.

Widget file and folder hierarchy

All widget's resource locates in widget root folder. But widget can access external resources when it has been loaded in widget runtime if it declares the external resource permission in its configuration document.

A widget resource contains a configuration document, named 'config.xml' in the widget's root folder.

A widget resource must contain at least one start file. The widget runtime attempts to locate the start file following the process for finding a start file defined in.

Default start files are identified by the filename 'index.html'. Widget authors may declare a specific file to be used by the widget runtime as the start file by using the 'content' element of the configuration document.

One widget resource may contain one or more JavaScript files. Author is allowed to organize all JavaScript files into certain sub folder. For example, all JavaScript files are located in sub folder 'js'.

A widget resource can contain one or more CSS files. Author is allowed to organize all CSS files into certain sub folder. For example, all CSS files are located in sub folder 'css'.

Configuration Document

Configuration document is named as 'config.xml' and should be in lower case form. Configuration document describes the meta properties of a widget. It must include mandatory element that describing basic information of this widget, like author, size, permission and etc. The detailed specifications are described as below.
A sample configuration document config.xml can be like:

<?xml version="1.0" encoding="utf-8" ?>
<widget xmlns=”http://www.jil.org/ns/widgets”
id="http://www.jil.org/d468221321b454fc001ff447563dd737afe6d6ffdbcc2c815aa08b5527f943c7/gogowidget"
version=”01.00.Beta”
height=”150”
width=”100”>
<name>Widget Example</name>
<description>An example widget</description>
<author email=”[e-mail]”>czheng</author>
<icon src=”icon.png”/>
<license href="http://creativecommons.org/licenses/by/3.0/">
Creative Commons Attribution License
</license>
<access network=”true” localfs=”true” remote_scripts=”false”/>
<content src=”myWidgetContent.html“/>
<feature name=”http://jil.org/jil/api/1.1/filesystem” required=”true”/>
<feature name=”http://jil.org/jil/api/1.1/calendar” required=”false”/>
<maximum_display_mode height=”300” width=”200”/>
</widget>

The configuration document namespace must be “http://www.jil.org/ns/widgets”, i.e. the widget element is assigned to the namespace defined in this document as follows: <widget xmlns=“http://www.jil.org/ns/widgets“>

Widget Element

Configuration document must contain following widget element as its root element:

'widget' element describes widget information in configuration documents. It serves as a container for other elements and it must be used in configuration document.

'widget' element have following child elements:

• name: zero or one
• description: zero or one
• author: zero or one
• license: zero or one
• icon: zero or one
• access: zero or one
• content: zero or one
• feature: zero or more
• maximum_display_mode:zero or one

'widget' element may have following attributes:

• id: one
• version: zero or one
• height: zero or one
• width: zero or one

'id' attribute of the 'widget' element represents a unique identifier for the widget in the form of a URI. The 'id' attribute MUST be included by the widget author for submission to the JIL developer portal. The exact format of id must follow the rule set by developer website.

'version' attribute of 'widget' element indicates the current version of widget. It is required when widget runtime perform an update process.

'version' strings should comply to the following ABNF rule:

jil-rec-version-tag = major-version "." minor-version ["." version-desc]
major-version = 2DIGIT; two digits from 0-9
minor-version = 2DIGIT; two digits from 0-9
version-desc = 1*10ALPHA; optional version description in 1 to 10 Upper- and
lower-case ASCII letters (A–Z, a–z)

Examples of recommended version values that are compliant to the jil-rec-version-tag are:

01.01;
01.01.beta;
99.99.testBetaXY.

'height' attribute of 'widget' element indicates the widget default view's height in CSS pixels. If this attribute is missing, widget runtime may choose a pre-defined integer value that defined by itself instead.

'width' attribute of 'widget' element indicates the widget default view's width in CSS pixels. If this attribute is missing, widget runtime may choose a pre-defined integer value that defined by itself instead.

Name Element

'name' element represents the human-readable name for a widget resource that can be used, for example, in application menus or in other contexts. If the name is not specified, the name of the widget package file will be used.

Description Element

'description' element represents a human-readable description of the widget.

Author Element

'author' element may have the following attributes:

• email: zero or one

'author' element represents a person or an organization involved in the creation of the widget.

License Element

'license' element MAY have the following attributes:

• href: zero or one

'license' element represents an end-user license agreement or a copyright statement. The license may be located at the 'href' attribute if present or within the content of the 'license' element.

Below is an example of the license contained only in the content of the element:

<widget xmlns:jil=“http://www.jil.org/ns/widgets”>
<license>
Copyright (c) 2008 The Foo-Bar Corporation
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.</license>
</widget>

'href' attribute of the 'license' element is a valid URI that points to the representation of a software and/or content license.If the 'href' is present the widget runtime allow the users to view or otherwise access the referenced license.

Below is an example of the 'href' attribute being used:

<widget xmlns:jil=“http://www.jil.org/ns/widgets”>
<license href=http://creativecommons.org/licenses/by/3.0/>
Creative Commons
</license>
</widget>

Icon Element

'icon' element must have the following attributes:

• src: one

'icon' element represents an icon for the widget. The widget runtime exposes an icon in a way that it is visible to the end user.

'src' attribute of the 'icon' element contains a valid path to an image file inside the widget resource.

Access Element

'access' element describes the permissions, in addition to the APIs requested using the 'feature' element that the widget is requesting from the widget runtime. Of course, widget runtime is allowed to deny such access requests. It is not a mandatory element in configuration file.

'access' element may have following attributes:

• network: zero or one
• localfs: zero or one
• remote_scripts: zero or one

'network' attribute indicates whether of the widget can access an online web resources through HTTP/HTTPS. The allowed values of this attribute are “true” and “false”. “true” means the widget is requesting access to online web resources using HTTP/HTTPS. “false”means the widget is not requesting access to online web resources using HTTP/HTTPS and the widget runtime does not allow the widget to access the network.

If this attribute is missing, the default value is “false”.

'localfs' attribute indicates whether the widget can access resources that resides on device's file system. The allowed values of this attribute are “true” and “false”. “true” means the widget is requesting access to the device's local file system. “false” means the widget is not requesting access to the device's local file system and the widget runtime does not allow the widget to access the resources residing on the device's local file system.

If this attribute is missing, the default value is “false”.

'remote_scripts' attribute indicates whether this widget is allowed to fetch and load javascript files that reside outside of the widget resource, for example on remote web server. The allowed values of this attribute are “true” and “false”. “true” means the widget is requesting access to scripts outside of the widget resource. “false” means the widget is not requesting access to scripts outside of the widget resource and the widget runtime does not allow the widget load remote scripts.

If this attribute is missing, the default value is “false”.

i.e.:
<widget xmlns:jil="http://jil.org/ns/widgets">
…
<access network=”true” localfs=”true” remote_scripts=”false”/>
…
</widget>

Content Element

'content' element must have the following attributes:

• src: one

'content' element is used by an author to declare which resource the widget runtime will use when it instantiates the widget. If this element is missing, the widget runtime will search the widget root folder for 'index.html'. If the file does not exist, the widget runtime will consider this widget to be invalid and the installation will fail.

'src' attribute of the 'content' element points to a file within the widget resource.

Feature Element

'feature' element indicates what sensitive API or API groups this widget declares that it may attempt to access. The feature element should be viewed as a request by the widget to bind to runtime component –an API - identifiable by URI.

e.g.,
<feature name=”http://jil.org/jil/api/1.1/filesystem” required=”true”/>

'feature' element MUST have the following attribute:

• name

'feature' element MAY have the following attribute

• required

'name' attribute of the 'feature' element indicates the identity of the API required by the widget at runtime.

'required' of the 'feature' element attribute indicates whether this API or API group is critical or for the widget to operate correctly. The allowed values of this attribute are “true” and “false”. “true” means without access to these APIs or API groups, the widget can't run. “false” means without access to these APIs or API groups, the widget can run but may not run with full functionality or in the way that the author expects. The default value of the 'required' attribute if omitted is “false”.

If any of the API or API group identified by the 'name' attribute of the 'feature' element are unknown to the widget runtime and the 'required' attribute value for that 'feature' element is “false”, then they are removed from the requested permissions. If any of the API or API group are unknown to the device and marked as the 'required' attribute value for that 'feature' element is “true”, the widget MUST NOT be installed.

JIL API <feature> Tag Support

All restricted handset APIs must be declared in the widget's config.xml via the <feature> tag. This tag requires a “name” attribute containing a URI representative of the API to be used. The <feature> tag may optionally contain a “required” attribute. E.g., <feature name=”http://jil.org/jil/api/1.1/Camera” required=”false”/>

It is not necessary for a widget to declare any unrestricted APIs using the <feature> tag. E.g., if a widget calls “AudioPlayer.open”, it is not necessary for the widget's config.xml to declare the use of the AudioPlayer API. However, if the widget calls “CalendarItem.update”, then it is necessary for the config.xml to contain a <feature> with the Calendar API's URI.

The following table identifies the APIs and their corresponding <feature> tag URIs.

Object	API/Attribute/Event	Feature URI
Widget	onMaximize()	Unrestricted
Widget	onRestore()	Unrestricted
Widget	onFocus()	Unrestricted
Widget	onWakeup()	Unrestricted
Widget	openURL()	http://jil.org/jil/api/1.1/url
Widget	preferenceForKey()	Unrestricted
Widget	setPreferenceForKey()	Unrestricted
CallRecord	callRecordAddress	Unrestricted
CallRecord	callRecordId	Unrestricted
CallRecord	callRecordName	Unrestricted
CallRecord	callRecordType	Unrestricted
CallRecord	durationSeconds	Unrestricted
CallRecord	startTime	Unrestricted
Telephony	deleteCallRecord()	http://jil.org/jil/api/1.1/telephony
Telephony	findCallRecords()	http://jil.org/jil/api/1.1/telephony
Telephony	getCallRecord()	http://jil.org/jil/api/1.1/telephony
Telephony	getCallRecordCnt()	http://jil.org/jil/api/1.1/telephony
Telephony	initiateVoiceCall()	http://jil.org/jil/api/1.1/telephony
Telephony	onCallRecordsFound()	Unrestricted
Telephony	onCallEvent()	Unrestricted
Messaging	createMessage(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	deleteMessage(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	findMessages(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	getMessage(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	getMessageQuantities(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	onMessageArrived(SMS)	Unrestricted
Messaging	sendMessage(SMS)	http://jil.org/jil/api/1.1/messaging
Messaging	onMessageFound()	Unrestricted
Messaging	onMessageSendingFailure()	Unrestricted
Message	addAddress()	Unrestricted
Message	deleteAddress()	Unrestricted
Message	bccAddress	Unrestricted
Message	body	Unrestricted
Message	callbackNumber	Unrestricted
Message	ccAddress	Unrestricted
Message	destinationAddresses	Unrestricted
Message	isRead	Unrestricted
Message	messageId	Unrestricted
Message	messagePriority	Unrestricted
Message	messageType	Unrestricted
Message	sourceAddress	Unrestricted
Message	subject	Unrestricted
Message	time	Unrestricted
Message	validityPeriodHours	Unrestricted
Multimedia	isAudioPlaying	Unrestricted
Multimedia	getVolume()	Unrestricted
Multimedia	stopAll()	Unrestricted
AudioPlayer	pause()	Unrestricted
AudioPlayer	open()	Unrestricted
AudioPlayer	play()	Unrestricted
AudioPlayer	resume()	Unrestricted
AudioPlayer	stop()	Unrestricted
AudioPlayer	onStateChange()	Unrestricted
Device	copyFile()	http://jil.org/jil/api/1.1/filesystem
Device	deleteFile()	http://jil.org/jil/api/1.1/filesystem
Device	moveFile()	http://jil.org/jil/api/1.1/filesystem
Device	getDirectoryFileNames()	http://jil.org/jil/api/1.1/filesystem
Device	getFile()	http://jil.org/jil/api/1.1/filesystem
Device	getFileSystemRoots()	Unrestricted
Device	getFileSystemSize()	Unrestricted
Device	onFilesFound()	Unrestricted
Device	findFiles()	http://jil.org/jil/api/1.1/filesystem
DeviceInfo	totalMemory	Unrestricted
DeviceInfo	phoneFirmware	Unrestricted
DeviceInfo	phoneScreenHeightDefault	Unrestricted
DeviceInfo	phoneScreenWidthDefault	Unrestricted
DeviceInfo	phoneColorDepthDefault	Unrestricted
DeviceInfo	phoneModel	Unrestricted
DeviceInfo	phoneSoftware	Unrestricted
DeviceInfo	phoneManufacturer	Unrestricted
DeviceInfo	phoneOS	Unrestricted
DeviceStateInfo	availableMemory	Unrestricted
DeviceStateInfo	language	Unrestricted
Config	setDefaultRingtone()	http://jil.org/jil/api/1.1/config
Config	msgRingtoneVolume	http://jil.org/jil/api/1.1/config
Config	ringtoneVolume	http://jil.org/jil/api/1.1/config
Config	setAsWallpaper()	http://jil.org/jil/api/1.1/config
Config	vibrationSetting	http://jil.org/jil/api/1.1/config
File	createDate	Unrestricted
File	fileName	Unrestricted
File	filePath	Unrestricted
File	fileSize	Unrestricted
File	isDirectory	Unrestricted
File	lastModifyDate	Unrestricted
PowerInfo	percentRemaining	Unrestricted
PowerInfo	isCharging	Unrestricted
PowerInfo	onChargeStateChange()	Unrestricted
RadioInfo	onSignalSourceChange()	Unrestricted
PIM	addAddressBookItem()	http://jil.org/jil/api/1.1/addressbook
PIM	deleteAddressBookItem()	http://jil.org/jil/api/1.1/addressbook
PIM	findAddressBookItems()	http://jil.org/jil/api/1.1/addressbook
PIM	getAddressBookItem()	http://jil.org/jil/api/1.1/addressbook
PIM	getAddressBookItemsCount()	http://jil.org/jil/api/1.1/addressbook
PIM	getCalendarItem()	http://jil.org/jil/api/1.1/calendar
PIM	getCalendarItems()	http://jil.org/jil/api/1.1/calendar
PIM	addCalendarItem()	http://jil.org/jil/api/1.1/calendar
PIM	deleteCalendarItem()	http://jil.org/jil/api/1.1/calendar
PIM	findCalendarItems()	http://jil.org/jil/api/1.1/calendar
PIM	onAddressBookItemsFound ()	Unrestricted
PIM	onCalendarItemAlert()	Unrestricted
PIM	onCalendarItemsFound()	Unrestricted
CalendarItem	alarmDate	Unrestricted
CalendarItem	calendarItemId	Unrestricted
CalendarItem	eventEndTime	Unrestricted
CalendarItem	eventName	Unrestricted
CalendarItem	eventNotes	Unrestricted
CalendarItem	eventRecurrence	Unrestricted
CalendarItem	eventStartTime	Unrestricted
CalendarItem	update()	http://jil.org/jil/api/1.1/calendar
AddressBookItem	address	Unrestricted
AddressBookItem	addressBookItemId	Unrestricted
AddressBookItem	company	Unrestricted
AddressBookItem	eMail	Unrestricted
AddressBookItem	fullName	Unrestricted
AddressBookItem	homePhone	Unrestricted
AddressBookItem	mobilePhone	Unrestricted
AddressBookItem	titile	Unrestricted
AddressBookItem	workPhone	Unrestricted
AddressBookItem	getAttributeValue()	Unrestricted
AddressBookItem	getAvailableAttributes()	Unrestricted
AddressBookItem	setAttributeValue()	Unrestricted
AddressBookItem	update()	http://jil.org/jil/api/1.1/addressbook

Maximum Display Mode Element

‘maximum_display_mode’ element describes the widget’s behavior and appearance when it is showed in full screen view. When a widget is running in maximum_display_mode, that widget is the only one rendered by the widget user agent and takes over the whole screen.

If either of the dimensions indicated the maximum_display_mode’s height and width attributes are smaller than the dimensions of the screen, the widget runtime renders the widget according to smaller dimension provided by the height or width attributes, center the widget on the screen and fill the surrounding space with a background graphic.

If either of the dimensions indicated the maximum_display_mode’s height and width attributes are larger than the dimensions of the screen, the widget user agent SHALL render the widget according to the dimensions of the screen.

When moving between the default display mode and the maximum_display_mode the widget runtime will re-size the widget according to the behaviour for rendering a widget in fullscreen display mode as described above.

When moving from maximum_display_mode and the default mode the widget runtime will re-size the widget according to the behaviour for rendering a widget in the default mode.

The maximum_display_mode is an optional element. If omitted, the widget runtime will size the widget to the size of the screen when it is rendered in fullscreen display mode.

‘maximum_display_mode’ element has the following attributes:

• height: zero or one
• width: zero or one

‘height’ element represents the height of maximum displayed widget in CSS pixels. If the attribute is missing, widget runtime uses the height of the screen.

‘width’ element represents the width of maximum displayed widget in CSS pixels. If the attribute is missing, widget user agents SHOULD use the width of the screen.

The ‘maximum_display_mode’ and its attributes MUST be bound to the JIL namespace, i.e.:

<widget xmlns="http://jil.org/ns/widgets">
…
<maximum_display_mode height=”200” width=”100”>
…
</widget>