blackberry widget sdk development guide 835918 0406095013 001 1.0 us

BlackBerry Widget SDKVersion: 1.0

Development Guide

SWD-835918-0420101057-001

Contents1 BlackBerry Widget applications................................................................................................................................................ 3

BlackBerry Widget SDK.................................................................................................................................................................. 3

BlackBerry Widget Packager.......................................................................................................................................................... 3

Communication............................................................................................................................................................................... 3

2 Creating BlackBerry Widget projects....................................................................................................................................... 5

Developing, running, and distributing a BlackBerry Widget application................................................................................. 5

Creating a BlackBerry Widget archive.......................................................................................................................................... 5

Specifying the start file for a BlackBerry Widget application........................................................................................... 5

Specifying the icons for a BlackBerry Widget application................................................................................................. 6

Reserved file names and folder names................................................................................................................................ 6

Creating a BlackBerry Widget configuration document............................................................................................................. 7

Code sample: Creating a BlackBerry Widget configuration document........................................................................... 7

BlackBerry Widget namespace...................................................................................................................................................... 8

Widget element............................................................................................................................................................................... 8

Name element........................................................................................................................................................................ 10

Description element............................................................................................................................................................... 10

Author element....................................................................................................................................................................... 11

License element...................................................................................................................................................................... 12

Icon element........................................................................................................................................................................... 13

Access element....................................................................................................................................................................... 13

Feature element...................................................................................................................................................................... 14

Content element..................................................................................................................................................................... 15

RIM loadingScreen element.................................................................................................................................................. 15

RIM connection element....................................................................................................................................................... 18

3 Securing BlackBerry Widget applications................................................................................................................................ 20

Allowing access to external resources and APIs......................................................................................................................... 20

Code sample: Allowing requests to any web site............................................................................................................... 20

Code sample: Allowing feature requests to specific web sites......................................................................................... 21

4 Compiling BlackBerry Widget applications............................................................................................................................. 22

Compiling a BlackBerry Widget..................................................................................................................................................... 22

Compile a BlackBerry Widget........................................................................................................................................................ 22

Compilation parameters........................................................................................................................................................ 23

Code sample: Compiling an unsigned BlackBerry Widget archive................................................................................... 23

Code sample: Compiling a signed BlackBerry Widget....................................................................................................... 23

Best practice: Compiling a BlackBerry Widget............................................................................................................................ 24

5 Signing .cod files for BlackBerry Widget applications........................................................................................................... 25

Install the new registry key with the BlackBerry Signature Tool............................................................................................... 25

Sign the .cod file for a BlackBerry Widget application............................................................................................................... 25

6 Testing BlackBerry Widget applications.................................................................................................................................. 27

Run a BlackBerry Widget on the BlackBerry Smartphone Simulator........................................................................................ 27

Run a BlackBerry Widget application on a BlackBerry device................................................................................................... 27

7 Making BlackBerry Widget applications available to BlackBerry device users................................................................. 29

8 Provide feedback......................................................................................................................................................................... 30

9 Legal notice.................................................................................................................................................................................. 31

BlackBerry Widget applications 1

BlackBerry® Widget applications are standalone BlackBerry device applications that consist of standard web components,including HTML, XHTML, style sheets, JavaScript® code, image files, and other resources. Widget applications follow the samesecurity rules, configuration, and deployment model as other BlackBerry device applications.

You can extend the capabilities of widget applications by using the widget APIs, which expose BlackBerry device capabilities.

Widget development is supported in BlackBerry® Device Software 5.0 or later.

BlackBerry Widget SDKYou can use the BlackBerry® Widget SDK to create BlackBerry Widget applications. The BlackBerry Widget SDK includes theBlackBerry® Widget Packager, the BlackBerry Smartphone Simulator, the BlackBerry MDS Connection Service, anddocumentation.

The widget application development process is tool independent. You can use any tool to create widget applications and thenuse the BlackBerry Widget Packager to compile the widget application for distribution. You can test the widget application byusing the BlackBerry Smartphone Simulator.

BlackBerry Widget PackagerThe BlackBerry® Widget Packager is a command prompt tool that compiles your web code to create a BlackBerry Widgetapplication. You can then distribute your widget applications to BlackBerry devices as you would other BlackBerry deviceapplications. The BlackBerry Widget Packager creates the output files you need for your distribution strategy, including theexecutable application file (.cod) for use with the BlackBerry App World™ and the installation file (.alx) for use with the BlackBerry®Desktop Manager.

CommunicationBlackBerry® Widget applications can support push and pull communication. If you develop an application that uses pullcommunication, you can use XMLHttpRequest objects as you would with AJAX development. You can use either synchronousor asynchronous pull communication. Any requests to external domains from your widget application must match the URLs thatyou provide by using widget permissions. Widget permissions provide a security mechanism that you use to protect the widgetapplication and the BlackBerry devices from potentially malicious users.

BlackBerry Widget applications support push technology. A backend server pushes application data to the widget applicationthat is running on a BlackBerry device. You can use the widget API methods blackberry.push() andblackberry.push.Data() to enable BlackBerry Widget applications to use the same BlackBerry® Enterprise Server andpublic data push infrastructure that other BlackBerry device applications use.

Development Guide BlackBerry Widget applications

3

BlackBerry Widget applications can run in the background, so that communication continues when the application is not theforeground application.

Development Guide Communication

4

Creating BlackBerry Widget projects 2

Developing, running, and distributing a BlackBerry Widget applicationWhen you develop a BlackBerry® Widget application, you perform the following actions:

1. Develop the HTML, style sheet, and JavaScript® code for your widget application.

2. Create a configuration document, which is the config.xml file that contains the details about your widget application.

3. Create the widget archive, which is a .zip file that consists of the widget code, config.xml file, and resources.

4. Compile and package the widget by using the BlackBerry® Widget Packager.

5. Install and test the widget in the BlackBerry Smartphone Simulator or on a BlackBerry device, both running BlackBerry®Device Software 5.0 or later.

6. Sign the widget with a Research In Motion code signing key.

7. Distribute the widget to BlackBerry device users.

Creating a BlackBerry Widget archiveA BlackBerry® Widget archive is a .zip file that you compile by using the BlackBerry® Widget Packager to create a widgetapplication.

The widget archive contains the following resources:• configuration document• start page• application icons• other resources and objects that are referenced in your web pages

When you create a widget, you should store it outside of the BlackBerry Widget Packager installation folder.

Specifying the start file for a BlackBerry Widget application

The start file for a BlackBerry® Widget specifies the screen that the widget displays when it starts. If you do not explicitly specifya start file by using the content element in the configuration document, or if there is an error in the definition, the widget usesa default start file. You can also specify a URL to use a remote file outside of the widget archive.

The default names for the start file, in search order, are index.htm and Index.html. The default MIME type is text/html. Defaultstart file names are case insensitive.

Development Guide Creating BlackBerry Widget projects

5

Specifying the icons for a BlackBerry Widget application

You can specify the images to use as the application icons for your BlackBerry® Widget application. The icons are optional. Youcan include icons to represent two states (selected and not selected) for the widget on the BlackBerry device.

You cannot specify an image in a configuration document that is outside of the BlackBerry Widget archive. You can, however,use the widget API to specify an external resource by using JavaScript® code.

Application icons

The application icon is the image that appears when the BlackBerry® device user has not yet selected the BlackBerry® Widgetapplication.

The default files name for the application icons are image.gif, image.jpg, or image.png, and the file must exist in the root folderof the widget archive. When you compile your widget, the BlackBerry® Widget Packager searches first for the image.png file, theimage.gif file, and then for the image.jpg file. The file name is case insensitive.

You can specify the application icon by using the icon element in the configuration document for your widget (for example,<icon src="icons/appicon.gif"/>).

If you specify the application icon in the configuration document, the BlackBerry Widget Packager does not search the root folderfor default icon files at compile time.

Hover icons

The hover icon is the image that appears when the BlackBerry® device user selects the BlackBerry Widget application.

You can specify the hover icon by using the icon element in the configuration document for your widget (for example, <iconsrc="icons/appfocus.gif" rim:hover="true"/>).

If you do not specify a hover icon in the configuration document, the default application icon appears when the user selects thewidget.

Reserved file names and folder namesThe file names that are reserved by the BlackBerry® Widget Packager are case insensitive.

The bin and src folders in the BlackBerry Widget Packager installation folder are not reserved, but you should not use them forproject resources. The bin folder and its contents are overwritten at compile time with compiled output. The src folder is overwrittenif you specify the option to save the source files at compile time.

Development Guide Creating a BlackBerry Widget archive

6

Reserved name Description

config.xml This file name is reserved for the widget configuration document.

signature[0..9].xml These file names are reserved for the BlackBerry Signature Tool configuration file.

icon.gif, icon.jpg, icon.png These file names are reserved for the default icon image.

Thumbnail.gif, Thumbnail.png These file names are reserved for thumbnail graphics.

index.htm, index.html These file names are reserved for the default start page.

Creating a BlackBerry Widget configuration documentThe BlackBerry® Widget configuration document is an .xml file that contains the elements to define the namespace, the nameof the widget, widget permissions, the start page, and the icons to use for the widget application. It also contains the elementsthat define information such as the author, email address, and license information. The widget configuration document containsthe widget element at its root. The widget element provides a container for all other elements.

The configuration document must be located in the root folder of the BlackBerry Widget archive.

Code sample: Creating a BlackBerry Widget configuration documentA valid file name for a BlackBerry® Widget configuration document is config.xml, and is case insensitive. Within the widgetarchive, the configuration document must use this file name. The config.xml file must exist in the root folder of the widget archive.

<?xml version="1.0" encoding="utf-8"?><widget xmlns=" http://www.w3.org/ns/widgets" xmlns:rim="http://www.blackberry.com/ns/widgets" version="2.0" rim:header="RIM-Widget: rim/widget" rim:navigationMode="true">

<name> The example widget</name>

<description> A sample widget to demonstrate some of the possibilities. </description>

<rim:loadingScreen backgroundImage="background.png" foregroundImage="foreground.gif" onLocalPageLoad="true"> <rim:transitionEffect type="zoomIn" /> </rim:loadingScreen>

<icon src="icons/example.png"/> <icon src="icons/boo.png" rim:hover="true"/>

Development Guide Creating a BlackBerry Widget configuration document

7

<content src="index.html"/>

<feature id="blackberry.ui.dialog" required="true" version="1.0.0"/> <access uri="http://www.somedomain.com" subdomains="true"> <feature id="blackberry.pim.memo" required = "true" version="1.0.0"/> <feature id="blackberry.invoke.MemoArguments" required = "true" version="1.0.0"/> </access>

<rim:connection timeout="25"> <id>TCP_WIFI</id> <id>MDS</id> <id>BIS-B</id> <id>TCP_CELLULAR</id> <id>WAP2</id> <id>WAP</id> </rim:connection>

<license> Example license Copyright (c) 2008 My Corp. 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, INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

</license>

</widget>

BlackBerry Widget namespaceYou must assign the BlackBerry® Widget namespace to the widget element. If the namespace is missing, the widget archiveis invalid. The namespace for BlackBerry® Widget extensions is optional.

The widget namespace is http://www.w3.org/ns/widgets. The namespace for BlackBerry specific widget extensions isxmlns:rim http://www.blackberry.com/ns/widgets.

Widget elementThe widget element provides a container for all other elements, and is the root element in the configuration document.

Development Guide BlackBerry Widget namespace

8

For all other elements within the widget element, you use the following order:• one name element• zero or one description elements• zero or more icon elements• zero or one author elements• zero or one license elements• zero or more access elements• zero or one content elements• zero or more feature elements• zero or one rim:loadingScreen elements• zero or one rim:loadingScreen elements• zero or one rim:transitionEffect elements

Attribute Description

version The version attribute specifies a valid version for the BlackBerry® Widget

application, in one of the following formats:

• x.x

• x.x.x

• x.x.x.x

If you specify an invalid version number, the widget archive is invalid.

This attribute is required.

rim:header The rim:header attribute specifies a header value that precedes every request

for data from the widget. This header enables you to distinguish widget requests

from BlackBerry® Browser requests.

This attribute is optional.

rim:backButton The rim:backButton attribute specifies the behavior for the Back button on the

BlackBerry device. If you specify this attribute, the Back button exits the widget.

By default, the Back button displays the previous screen.


id The id attribute specifies a unique identifier for the widget.


Development Guide Widget element

9


xml:lang The xml:lang attribute specifies the language that is used in the element, for

example, en for English.


Name element

The name element specifies a human-readable name for a BlackBerry® Widget application that you can use, for example, in anapplication menu.

If you do not specify a name element, the widget is not valid.

You can also specify a name by using the blackberry.app.name that is provided in the BlackBerry Widget API.


xml:lang The xml:lang attribute specifies the language that is used in the element.


its:dir The its:dir attribute specifies the directionality of the language. For example,

its:dir="rtl" specifies a language that is written from right to left.

You can use this attribute for localization.

Code sample: Specifying a name<name>Hello World! Widget</name>

Description element

The description element provides a human-readable description for a BlackBerry® Widget application.

You can access this element by using blackberry.app.description in the BlackBerry Widget API.


xml:lang The xml:lang attribute specifies the language that is used in the element.



10


its:dir The its:dir attribute specifies the directionality of the language. For example,

its:dir="rtl" specifies a language that is written from right to left.

You can use this attribute for localization.

Code sample: Specifying a description<description> This widget displays "Hello World" on the screen.</description>

Author element

The author element specifies the people or an organization that is involved with the creation of a BlackBerry® Widget application.Author information appears in the Vendor property when you view the list of applications that are installed on the BlackBerrydevice.

You can access this element by using blackberry.app.author in the BlackBerry Widget API.


href The href attribute specifies a web address that is associated with the author; for

example, the web page of the author.

You can access this attribute by using blackberry.app.authorURL in the

BlackBerry Widget API.

rim:copyright The rim:copyright attribute specifies copyright information for the About

screen of the widget and the copyright area in the applications list on the BlackBerry

device. An example of typical copyright text is Copyright 1998-2009 My

Company Inc.

This attribute is optional. You can access this attribute by using

blackberry.app.copyright in the BlackBerry Widget API.

email The email attribute specifies the email address that is associated with the author.

You can access this attribute by using blackberry.app.authorEmail in the

BlackBerry Widget API.



11


xml:lang The xml:lang attribute specifies the basic language range.


its:dir This attribute is optional.

License element

The license element specifies the end user license agreement or a copyright statement for a BlackBerry® Widget. This elementis optional. If it is specified, the BlackBerry® device user is prompted to accept or decline the license agreement when the widgetruns for the first time. After users agree to the license terms, the prompt does not appear when they run the widget again.

The contents of the license agreement are also available in the About screen for the widget.


xml:lang The xml:lang attribute defines the basic language range.


its:dir This attribute is optional.

href The href attribute specifies a web address that contains content or license

information.


Code sample: Providing a license web page<license> Example license Copyright (c) 2008 My Corp. 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, INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</license>


12

Icon element

The icon element specifies a custom icon for a BlackBerry® Widget application. You can specify one or more icon elements.The first icon that does not have the rim:hover attribute set to True is used as the main icon for the widget on the BlackBerrydevice. The icon must meet the requirements for custom or default icons. This element is optional.

If you do not specify the icon element, the BlackBerry® Widget Packager uses the default icon from the widget archive. If theBlackBerry Widget Packager does not find the default icon in the archive, it uses the default device application icon.

You can also specify an icon by invoking blackberry.app.setHomeScreenIcon(src, rim:hover) in the BlackBerryWidget API.


src The src attribute specifies the path for an image file in the widget archive.


rim:hover The rim:hover attribute is a Boolean value that specifies that the icon is used as

the hover icon on the device Home screen. The first hover icon in the configuration

document is used as the hover icon for the widget.

This attribute is optional. By default, if you do not specify a value for the

rim:hover attribute, the value is set to False.

Code sample: Specifying application icons<icon src="icons/appicon.png"/><icon src="icon/hovicon.png rim:hover="true"/>

Access element

The access element allows a BlackBerry® Widget application to access external network resources. By default, if you do notspecify an access element, a widget has access to all local resources. Local resources include any resources in the widgetarchive file.


URI The URI attribute defines the web address for the access request.



13


subdomains The subdomains attribute is a Boolean value that indicates whether the host

component in the access request applies to subdomains of the domain that is

specified in the URI attribute.


By default, if you do not specify the value of the subdomains attribute, the value

is set to False and no access to subdomains is requested.

If your widget makes calls to APIs on an external server, the external server must be declared in the proxy list.

Code sample: Allowing access to external network resources and features<access URI="http://www.mydomain.com" subdomains="true"> <feature id="blackberry.pim.memo" required="true" version="1.0.0"></access>

Feature element

The feature element specifies an API that a BlackBerry® Widget application can use. You can use the feature elementwithin the access element to access a feature under the external domain. You can also use the feature element at the rootof the configuration document, before any access elements, for access to the local page.

If you do not specify an access element above the feature element, the local domain is used. If you do not specify an API asa feature, the widget cannot use the API for the specified domain.


id The id attribute specifies the name of the BlackBerry API. The value must match

the name of the API, but is not case sensitive. You cannot use a wildcard (*) to use

multiple namespaces at the same time.


required The required attribute is provided to conform to the W3C® specification.


version The version attribute specifies the library version of the API.



14

Code sample: Specifying access to a feature<feature id="blackberry.ui.dialog" required="true" version="1.0.0"/><access uri="http://www.somedomain.com" subdomains="true"> <feature id="blackberry.pim.memo" required="true" version="1.0.0"/> <feature id="blackberry.invoke.MemoArguments" required="true" version="1.0.0"/></access>

Content element

The content element specifies the start page that the BlackBerry® Widget application uses when it runs. If you do not specifya content element, the widget uses a default start page from within the widget archive. The start page can contain the webaddress of a remote file that is located outside of the widget archive.


src The src attribute specifies the source HTML file in the widget archive.


type The type attribute specifies the MIME type of the file that is specified in the

src attribute.


charset The charset attribute specifies the character set that is used by the file that is

specified in the src attribute.


Code sample: Specifying a start page<content src="startpage.html"/>

RIM loadingScreen element

The rim:loadingScreen element specifies the properties of the loading screen that appears when the BlackBerry® Widgetapplication starts. This element is optional.


backgroundColor The backgroundColor attribute defines the hexadecimal color value to display

as the background before the start page appears.


15


This attribute is optional. By default, if you do not specify a color, the background

is set to white.

backgroundImage The backgroundImage attribute defines the path for a local image to display as

the background. You can use .png or .jpg files. The image will be scaled to fit the

entire screen.


foregroundImage The foregroundImage attribute defines the path for a local image to display as

the foreground. You can use .bmp, .jpg, .gif, .png, animated .gif, and transparent .png

files. The image will be centered on the loading screen.


onRemotePageLoad The onRemotePageLoad attribute specifies whether to display the loading

screen when the widget transitions to a page from a remote location, including

URLs that begin with http or https. The value for this attribute can be either

true or false.


onLocalPageLoad The onLocalPageLoad attribute specifies whether to display the loading screen

when the widget transitions to a page from a local location, including URLs that

begin with local:/// or file:///. The value for this attribute can be either

true or false.


onFirstLaunch The onFirstLaunch attribute specifies whether to display the loading screen

each time you start the widget. The value for this attribute can be either true or

false.


Code sample: Specifying the loading screen background color<rim:loadingScreen backgroundColor="#FFFFFF" />

Code sample: Displaying a background image when the widget starts<rim:loadingScreen backgroundImage="background.png" onFirstLaunch="true" />


16

Code sample: Displaying a background image on transitions from remote pagesThe following sample displays a background image when the widget starts, and displays a background image with a transitioneffect when the widget transitions from a remote page.<rim:loadingScreen backgroundColor="#FFFFFF" backgroundImage="background.png" onFirstLaunch="true" onRemotePageLaunch="true"> <rim:transitionEffect type="fadeIn" direction="left" /></rim:loadingScreen>

RIM transitionEffect element

The rim:transitionEffect element specifies the type and properties of a transition effect that appears when theBlackBerry® Widget application transitions between screens. The screen transition is not used for the initial loading screen, butyou must define it within the rim:loadingScreen element. This element is optional.


type The type attribute defines the transition effect to use between screens in the

widget.

You can use the following values for this attribute:

• slideIn

• slideOut

• fadeIn

• fadeOut

• wipeIn

• wipeOut

• zoomIn

• zoomOut


duration The duration attribute defines the number of milliseconds it takes for the

transition to complete.

The value for this attribute must be an integer between 250 and 1000. If you specify

a value greater than 1000, the value is set to 1000. If you specify a value less than

250, the value is set to 250.


17


This attribute is optional. If you do not specify a duration, the value is set to 250.

direction The direction attribute defines the direction of the screen effect. Values for this

attribute include left, right, up, and down. This attribute is valid for the

following effects:

• slideIn

• slideOut

• wipeIn

• wipeOut

This attribute is optional. If you do not specify a direction, the transition moves

toward the left side of the screen.

Code sample: Specifying a transition effect<rim:loadingScreen backgroundColor="#AAA000" onLocalPageLoad="true"> <rim:transitionEffect type="zoomIn" /></rim:loadingScreen>

RIM connection element

The RIM connection element specifies the connection preferences for the BlackBerry® device.


timeout The timeout attribute overrides the default timeout when the device attempts to

connect using a particular transport method. By default, if you do not specify a value

for this attribute, the device uses the timeout that device applications use.

You specify the default value in milliseconds. If you do not specify a valid numeric

value, the timeout that you specify is ignored.

The default timeout is 30000 ms.

Id elementThe id element specifies the type and order of the transport methods that you want to use for a BlackBerry® Widget application.This element is optional. By default, if you do not specify an id element, the connection manager uses the following order:


18

• MDS: BlackBerry® Enterprise Server• BIS-B: BlackBerry® Internet Service• TCP_WIFI: Wi-Fi® network• TCP_CELLULAR: Direct TCP stack• WAP2: WAP 2.0 gateway for a wireless service provider• WAP: WAP 1.0 gateway for a wireless service provider

If you specify more than one transport method, the BlackBerry device attempts to use the transport methods that you specify, inorder.

If TCP_WIFI is not set as the first transport method, it is not used, even if a Wi-Fi connection is enabled on the device.

If you are using BlackBerry Push data services, you must use the BlackBerry Internet Service transport method.

Code sample: Specifying transport methods<rim:connection timeout="25"> <id>MDS</id> <id>BIS-B</id> <id>TCP_WIFI</id> <id>TCP_CELLULAR</id> <id>WAP2</id> <id>WAP</id></rim:connection>


19

Securing BlackBerry Widget applications 3

The content of your BlackBerry® Widget application runs inside a standard BlackBerry device application, so the widget applicationcan use the same policy and security configuration that other BlackBerry device applications use. You must obtain a signing keyto sign the .cod file for your widget application. You do not need to sign an application to run it in the BlackBerry SmartphoneSimulator.

Inside a widget application, you can specify that the widget can access widget APIs for a domain in an executable context. Anexecutable context is a container in which you can run JavaScript® code within the context of a web page. An executable containercan be a page, a frame, or an iframe. If a local page provides the widget API with access to the menu, and linked in JavaScriptcode, you can include the domain by using widget permissions for the executable container without specifying any featureelements.

Allowing access to external resources and APIsBy default, BlackBerry® Widget applications cannot access data from external resources. For example, a widget cannot retrievean HTML page or make an AJAX request to a web service, unless you configure the widget to be able to do so.

To allow access to external resources and BlackBerry Widget APIs, you must define the resources and the APIs that you requirein the widget configuration document. You can define the list of domains that your BlackBerry Widget is allowed to access andthe BlackBerry Widget APIs that are allowed for each domain. You can define this list using widget permissions.

The BlackBerry® Widget Packager follows the same origin policy for the resources that are requested by matching them to entriesin the widget permissions list.

Whenever you retrieve content from external resources, consider the following best practices to help make the widget as secureas possible:• Provide JavaScript® access to sensitive APIs only to trusted and secure web sites.• Protect your communication channel by using HTTPS when you expose sensitive APIs to the domain.• Use the same precautions that you would use for a hosted web site, to protect against users with malicious intent.

Code sample: Allowing requests to any web siteIf your BlackBerry® Widget application accesses data from an unknown domain or changing domain, you can use the accesselement with the wildcard character to make sure that your requests are not blocked.

When you use the wildcard character, web pages that your widget accesses from an external source cannot access any of thewidget APIs.

In this example, all requests are allowed, as long as they do not require access to widget APIs.

<access uri ="*"/>

Development Guide Securing BlackBerry Widget applications

20

Code sample: Allowing feature requests to specific web sitesIf your BlackBerry® Widget application is designed to access functionality on a domain, you must use the access andfeature elements to specify the domain to make sure that your requests are not blocked.

For example, if you want to update or change menu items from a domain, you must specify the domain and the APIs that you require.

In this example, the features that you specify under the domain mydomain are allowed. The ellipses in the example representspecific APIs that your widget uses.

<access uri ="mydomain" subdomains="true"> <feature id=" . . . /> <feature id=" . . . /></access>

Development Guide Allowing access to external resources and APIs

21

Compiling BlackBerry Widget applications 4

When you compile a BlackBerry® Widget application, all of the resources in the widget archive, including a start page, aconfiguration document, icons, and other resources, are used to create one or more .cod files. You can install the resulting .codfiles on the BlackBerry Smartphone Simulator or on a BlackBerry device, just as you would install any other BlackBerry deviceapplication.

Compiling a BlackBerry WidgetWhen you compile a BlackBerry® Widget application, the BlackBerry® Widget Packager performs the following actions:

1. validates the contents of the BlackBerry Widget archive

2. creates the output target folder and clean up old files, if necessary

3. creates the source target folder if specified and cleans up old files, if necessary

4. Creates the following output:

• .cod file required for wireless distribution or distribution from a web page• .alx file required for distribution using BlackBerry® Desktop Manager• .jad file required for distribution from a web page• .cso file required for application signing• .csl file required for application signing

5. for a signed widget, updates the .cod file with a signed version

Compile a BlackBerry WidgetBefore you begin:

Create the BlackBerry® Widget archive with all the required elements and objects. Make sure that the bbwp.properties file existsand that the file paths are correct.

You must run the BlackBerry® Widget Packager from its installation folder.

1. At the command prompt, change to the installation folder for the BlackBerry Widget Packager.

2. Compile the widget by using the following syntax:

bbwp [drive:][path]archive [/s [dir]] [/[-]g [password]] [/o dir]

The BlackBerry Widget Packager displays multiple messages, and indicates a successful compile if the widget archivecontains no errors.

Development Guide Compiling BlackBerry Widget applications

22

Compilation parameters

Parameter Description

archive This parameter specifies the name of the BlackBerry® Widget archive to compile.

The widget archive is a .zip file.

/g This parameter signs the resulting .cod file by using a password. The default setting

is /-g for an unsigned widget.

The widget is signed only if you specify /g and a password.

/o This parameter saves the output files to the specified folder. If you do not use

the /o parameter with a folder, the output is saved to the same path as the widget

archive.

/s This parameter saves the source files. By default, if you specify /s without a folder,

the source files are saved to the same path as the widget archive. If you specify a

folder, the source files are saved in the src folder within the folder that you specify.

Code sample: Compiling an unsigned BlackBerry Widget archiveThe BlackBerry® Widget Packager uses the BlackBerry® Widget archive test.zip file to produce an unsigned version of the compiledapplication.bbwp test.zip

Code sample: Compiling a signed BlackBerry WidgetThe BlackBerry® Widget Packager uses the BlackBerry® Widget archive test.zip to produce the following output:• a signed version of the compiled application, in the .\compiled\test.cod file• templates that generate the .cod file, in the .\archive_source\src\blackberry\ folder• extracted files from test.zip, in the .\archive_source\src\ folder

bbwp c:\test.zip /g password /s archive_source /o compiled

Development Guide Compile a BlackBerry Widget

23

Best practice: Compiling a BlackBerry Widget

Best practice Description

Name the resources consistently and

correctly.

When you compile a BlackBerry® Widget, the BlackBerry® Widget Packager uses

various resources. The BlackBerry Widget Packager does not verify the file names,

so you must make sure that all the file names and file paths match the settings in

the widget configuration document.

The BlackBerry Widget Packager checks references to the widget permissions, the

start page, and the application icons.

You should use only alphanumeric file names and make sure that the names and

the references to them are case sensitive.

Verify that all the required elements are

in the widget configuration document.

At a minimum, you must define the namespace and specify the widget, version, and

name elements in the widget configuration document. You might require the author

element if your widget is distributed by another service or application. Check for

proper syntax in the configuration document and that it is a valid .xml file.

Make sure that the elements your widget

requires are defined in the widget

configuration document.

Some elements are not required by the BlackBerry Widget Packager but might be

required for your widget to run properly. Make sure that the widget permissions are

defined properly if the widget must be able to make requests to external domains,

and that feature elements are defined for any BlackBerry Widget APIs you use.

Development Guide Best practice: Compiling a BlackBerry Widget

24

Signing .cod files for BlackBerry Widget applications 5

The BlackBerry® Widget Packager includes the BlackBerry Signature Tool so that you can install a registration key and signthe .cod file of your BlackBerry Widget application.

Applications that use controlled BlackBerry Widget APIs require signatures from the BlackBerry® Signing Authority Tool. Youmust use the BlackBerry Signature Tool to request and receive signatures.

If you install a registration key before you install the BlackBerry Widget Packager, you should create an unsigned .cod file for awidget application and then sign the .cod file in the same way that you requested the registration key.

Install the new registry key with the BlackBerry Signature Tool1. Visit https://www.blackberry.com/SignedKeys and complete the registration form.

After you complete the form, Research In Motion sends an email message containing a .csi file. The .csi file contains a listof signatures and your registration information.

2. At the command prompt, navigate to the bin folder within the installation folder for the BlackBerry® Widget Packagerinstallation directory.

3. Type the following command, including the full path of the .csi file:java -jar SignatureTool.jar <.csi file path>

4. If a dialog box appears that indicates that a private key cannot be found, perform the following actions:

a. Click Yes.

b. Type a password for the private key.

c. Type the password to confirm it.

d. Click OK.

e. Move the mouse to generate random data for the new private key.

5. In the Registration PIN field, type the PIN that RIM provided.

6. In the Private Key Password field, type a password of at least eight characters. This is the private key password.

7. Click Register.

8. Click Exit.

Sign the .cod file for a BlackBerry Widget applicationYou can sign your BlackBerry® Widget application when you compile it, by using the password that you defined when you requestedand installed the registry key.

Use the BlackBerry® Widget Packager and specify the /g option with a password:

Development Guide Signing .cod files for BlackBerry Widget applications

25

https://www.blackberry.com/SignedKeys/

bbwp [drive:][path]archive [/s [dir]] [/[-]g [password]] [/o dir]

Development Guide Sign the .cod file for a BlackBerry Widget application

26

Testing BlackBerry Widget applications 6

Run a BlackBerry Widget on the BlackBerry Smartphone SimulatorBefore you distribute your BlackBerry® Widget application to users, you can test it using the BlackBerry Smartphone Simulator.The BlackBerry Smartphone Simulator enables you to run and view your widgets exactly as you would on a real BlackBerry device.

You can download additional BlackBerry Smartphone Simulators at http://na.blackberry.com/eng/developers/resources/simulators.jsp. You can view documentation for the BlackBerry Smartphone Simulator from the Help menu of the simulator.

Before you begin:

Successfully compile a BlackBerry Widget.

1. On the Start menu, select Programs > Research In Motion > BlackBerry Widget Packager > BlackBerry SmartphoneSimulator.

2. After the BlackBerry Smartphone Simulator starts and you can see the Home screen, on the File menu, select Load JavaProgram.

3. Navigate to the output folder for your BlackBerry Widget and select the widget .cod file you want to run.

4. Click Open.

5. On the Applications screen, open the Downloads folder.

6. In the Downloads folder, click the BlackBerry Widget you created.

Run a BlackBerry Widget application on a BlackBerry deviceYou can load a BlackBerry Widget application on a BlackBerry device by using the JavaLoader.exe file that is by default locatedin the \Program Files\Research In Motion\BlackBerry Widget Packager\bin folder.

Before you begin:

Compile a BlackBerry® Widget successfully.

1. Connect a BlackBerry device to the computer.

2. At the command prompt, navigate to the location of the JavaLoader.exe file.

3. Type the following command and pass in the parameters below:

JavaLoader [-usb] [-pport] [-bbps] [-wpassword] load file

Development Guide Testing BlackBerry Widget applications

27

http://na.blackberry.com/eng/developers/resources/simulators.jsp

http://na.blackberry.com/eng/developers/resources/simulators.jsp

Parameter Description

port This parameter specifies the serial port that the device connects to (default is COM1), or a device

PIN if the device connects to a USB port. You must also specify the -usb option.

bps This parameter specifies the bit rate speed to the serial port (default is 115200).

password This parameter specifies the password for the device if it is set.

file This parameter specifies one or more .cod files to load onto the device. If the widget .cod file is

not in the same folder as the JavaLoader.exe file, make sure that you provide the full path to

the .cod file.

Development Guide Run a BlackBerry Widget application on a BlackBerry device

28

Making BlackBerry Widget applications available toBlackBerry device users

7

You can use any of the following distribution methods to distribute BlackBerry® Widget applications to BlackBerry device users.

Distribution method Description

BlackBerry App World™

storefront

This method installs your widget using BlackBerry App World on a device. You use the .alx

and .cod files that are produced by the BlackBerry® Widget Packager for this method.

BlackBerry® Desktop Manager This method installs your widget directly on a connected device using the BlackBerry

Desktop Manager. You use the .alx file that is produced by the BlackBerry Widget Packager

for this method.

Wireless network using the

BlackBerry® Browser

This method installs your widget directly on a device over the wireless network. Users visit

a web page using the BlackBerry Browser on the device and download the application using

a link on the web page. The web server hosts the .jad and .cod files that are produced by

the BlackBerry Widget Packager.

BlackBerry Application Web

Loader

This method installs your widget on a device from a web page. Users connect their devices

to their computers and visit the web page that contains a link to the widget. A Microsoft®

ActiveX® control permits users to install the widget directly from the web page. The web

server hosts the .jad and .cod files that are produced by the BlackBerry Widget Packager.

Wireless push from the

BlackBerry® Enterprise Server

This method installs your widget on devices over the wireless network by pushing the widget

from the BlackBerry Enterprise Server to multiple devices on the network. The server hosts

the .cod and .alx files that are produced by the BlackBerry Widget Packager.

Development Guide Making BlackBerry Widget applications available to BlackBerry device users

29

Provide feedback 8

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Development Guide Provide feedback

30

http://www.blackberry.com/docsfeedback

Legal notice 9

©2010 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ andrelated trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S.and countries around the world.

Java and JavaScript are trademarks of Sun Microsystems, Inc. Microsoft, Windows, and ActiveX are trademarks of MicrosoftCorporation. W3C is a trademark of the Massachusetts Institute of Technology. Wi-Fi is a trademark of the Wi-Fi Alliance. Allother trademarks are the property of their respective owners.

This documentation including all documentation incorporated by reference herein such as documentation provided or madeavailable at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition,endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements,or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including,without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency,links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Servicesin this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLEFOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCEDHEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,

Development Guide Legal notice

31

http://www.blackberry.com/go/docs

FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS,LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITYFOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE,TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHESOR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B)TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITYARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions,endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® DesktopSoftware, and/or BlackBerry® Device Software.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIESPROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited295 Phillip Street


32

Waterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada


33

blackberry widget sdk development guide 835918 0406095013 001 1.0 us

Documents