You are on page 1of 19

Research In Motion

How to set up Eclipse for Widget development


For BlackBerry SmartPhones
Prosanta Bhattacherjee

09

2|Page

Contents
Introduction............................................................................................................................................. 3 Development ...........................................................................................................................................4 Creating a new web site ......................................................................................................................4 Further Documentation ........................................................................................................................19

3|Page

Introduction
This tutorial will go over how to set up the file structures necessary to create a simple BlackBerry Widget. It will demonstrate how to use basic BlackBerry Widget API calls to retrieve the device model, device PIN and interact with the Calendar application to todays date. The following is required to be able to use this tutorial: Windows XP or Vista Eclipse: Eclipse 3.4.1, EMF 2.4.1, WTP 3.0.3
Standalone 5.0 simulator

Java: Java 1.6

For help with setting up your environment please look at the tutorial How to install the BlackBerry Widget Packager found on the BlackBerry Developers Web Site (http://www.blackberry/developers/widget). A fully integrated Eclipse plug-in will be available in the future releases of the tooling. If you are ready to proceed, launch the Eclipse IDE.

Figure 1

4|Page

In this tutorial, we will demonstrate the following: How to create a new web project with the files necessary to create a widget Package your web application into a widget Use some basic APIs from the device to retrieve device information

Please note that you can find more information about the BlackBerry Widget Packager on the BlackBerry Developer Website (http://www.blackberry/developers/widget). Further documentation on Eclipse can be found through the Eclipse web site.

Development
Creating a new web site
1) From the file menu, select New then Other

Figure 2

5|Page 2) Choose Dynamic Web Project and then click Next

Figure 3

6|Page 3) Enter the project name

Figure 4
4) Click Finish

7|Page 5) Your screen should now contain the project in the Project Explorer

Figure 5

6)

Right click on the WebContent directory, and select New -> File

Figure 6

7) Name the file index.html and click Finish

8|Page

8) Create the following files in the same way that index.html was created: a. config.xml (This file is critical to a widget, it must be created for the compiler to work) b. action.js c. simple.css 9) Your Project Explorer should now look like this:

Figure 7

10) In the index.html file, paste in the following code. It is simple html that includes the style sheet and JavaScript file as well as some buttons to display the device model, PIN and launch the Calendar application:
<html> <head> <title>Widget API Basic Sample</title> <link rel="stylesheet" type="text/css" href="simple.css"></link> <script type="text/javascript" src="actions.js"></script> </head> <body> <div> <p> Widget API Basic Sample</p> </div> <div> <input type="button" value="What is the model of my device?" onclick="displayModel()" /> </div> <div>

9|Page
<input type="button" value="What is my PIN?" onclick="displayPin()" /> </div> <div> <input type="button" value="What do I have planned today?" onclick="launchCalendar()" /> </div> </body> </html>

11) In the action.js file, paste in the following code. It is the core of your widget application and contains the JavaScript code to call into the device API. These are some basic examples of how to interact with the device API, more details can be found in the Widget API Reference Document (http://www.blackberry.com/developers/widget):
// Display the device model function displayModel() { var model = blackberry.system.model; alert("The model of this device is " + model); } // Display the PIN of the device function displayPin() { var pin = blackberry.identity.PIN; alert("Your PIN is " + pin); } // Launch the calendar with today's date function launchCalendar(){ // Get today's date var today = new Date(); alert("Today is " + today.toString()); // Launch Calendar App with today's date var calendarArgs = new blackberry.invoke.CalendarArguments(today); calendarArgs.view = blackberry.invoke.CalendarArguments.VIEW_DAY; blackberry.invoke.invoke(blackberry.invoke.APP_CALENDAR, calendarArgs); }

10 | P a g e 12) In the simple.css paste in the following. This is just some simple styling to customize the application:
p{ font-weight: bold; } div { text-align: center; } input { width: 300px }

13) In the config.xml paste in the following. This is the configuration file that documents your widget. It contains entries describing the widget for the ALX file to be generated as well as any whitelists and feature lists that you are using. The ALX file is used by your Desktop Manager as a means to locate which cod files your application uses, as well as contains a description of your application:
<?xml version="1.0" encoding="utf-8" ?> <widget xmlns="http://www.w3.org/ns/widgets" xmlns:rim="http://www.blackberry.com/ns/widgets" version="1.0.0"> <name>Widget API Basic Sample</name> <description>A sample of basic Widget API usage</description> <author href="http://www.rim.com/" rim:copyright="no copyright" email = "widgetapi@rim.com"> Research in Motion - Widget API Team </author> <license href="http://www.license.com">This is a sample license</license> <content src="index.html" /> <feature id="blackberry.system" /> <feature id="blackberry.identity" /> <feature id="blackberry.location" /> <feature id="blackberry.invoke.CalendarArguments" /> <feature id="blackberry.invoke" /> </widget>

11 | P a g e 14) Now that the files have been set up, youll want to create a web directory in your BlackBerry Widget Packager install directory

Figure 8

12 | P a g e 15) Browse to the directory that is set as you workspace

Figure 9

13 | P a g e 16) Browse inside your project directory, and then inside the WebContent" directory

14 | P a g e 17) Select all of the files and create a zip file called BasicWidgetExample.zip

Figure 10

15 | P a g e 18) Move this zip file into the web directory that you created in step 14 19) Open a command prompt window and browse to the BlackBerry Widget Packager install directory 20) Run the command line bbwp.exe web/BasicWidgetExample.zip, and your command prompt should look like this when complete:

Figure 11
21) Congratulations! Youve just created your first BlackBerry Widget. Browse to the web directory, and there should now be a bin directory there containing the install files

Figure 12

16 | P a g e 22) To run the widget that you just created, start up the 5.0 simulator, and click File then Load Java Program

Figure 13

17 | P a g e 23) Browse to the cod file that you compiled (it will be in the bin directory that you created when you compiled the widget)

Figure 14

18 | P a g e 24) On your simulator, go to the Downloads folder, and youll see your application there

Figure 15
25) Select the application to run it

19 | P a g e

Further Documentation
BlackBerry Widgets Web Site: http://www.blackberry/developers/widget

BlackBerry Developers Web Site: http://na.blackberry.com/eng/developers/

BlackBerry App World: http://na.blackberry.com/eng/developers/appworld.jsp

BlackBerry Enterprise Server: http://na.blackberry.com/eng/services/server/

BlackBerry Web Loader: http://www.blackberry.com/developers/downloads/webloader/

Developer Video Library: http://na.blackberry.com/eng/developers/resources/videolibrary.jsp

Documentation: http://na.blackberry.com/eng/support/docs/developers/?userType=21

Knowledge Base Articles: http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/custo mview.html?func=ll&objId=348583

Forums: http://supportforums.blackberry.com/rim/?category.id=BlackBerryDevelopment