Research In Motion
How to avoid recompiling
a BlackBerry WebWorks
during development
For BlackBerry® Smartphones
Adam Stanley
09
2|Page
Contents
Overview .................................................................................................................................................3
Tasks ........................................................................................................................................................4
Notes .....................................................................................................................................................12
Links .......................................................................................................................................................13
3|Page
Overview
This tutorial will demonstrate how to structure a BlackBerry® Widget so that you can avoid having to
recompile and redeploy it when small changes are made to the web resources it uses (HTML,
JavaScript). The BlackBerry® Widget will be configured to loads these files from an external location
instead of as embedded resources.
In doing this, the Widget can be deployed to a BlackBerry® smartphone and/or simulator and will
not need to be re-compiled and re-deployed when small changes are made to the web content.
This practice is recommended for making the development of BlackBerry® Widgets more efficient. It
is not recommended to follow this practice when deploying an actual BlackBerry® Widget
application because the internal web resources would be vulnerable to modification.
System Requirements:
• Java Development Kit (JDK) 1.6 or higher
• BlackBerry® smartphone simulator 5.0.0.252 or higher
• BlackBerry® Widget Packager Installed
4|Page
Tasks
1. Create a new folder named avoidRecompile. Widget files that are to be created during this
tutorial will be saved in this folder.
C:\Program Files\Research In Motion\BlackBerry Widget
Packager\avoidRecompile
2. Ensure files in the avoidRecompile folder can be accessible by an HTTP web request.
http://localhost/avoidRecompile/
3. Creating the following named config.xml file in the avoidRecompile folder:
<?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 sample: Avoiding recompile</name>
<description> Enter your description </description>
<author href="http://www.yoursite.com/"
email="[email protected]">
Company Name – Developer Name
</author>
<content src="index.html" />
<feature id="blackberry.system" />
</widget>
The contents of this file define the properties and behavior of a BlackBerry® Widget. Right now
this file indicates that when launched, the BlackBerry® Widget will display the contents of an
embedded file named index.html.
5|Page
The “feature” element enables the Widget to have access to the blackberry.system
namespace in the BlackBerry® Widget API. Any embedded web resources, including the
index.html file will be able to access the properties and method from the
blackberry.system namespace. Without it, an exception would occur if the BlackBerry®
Widget attempted to access any of the methods or properties found in the
blackberry.system namespace.
For more information on widget security, please see the tutorial on “How to secure your
BlackBerry® Widget”.
4. Change the location from where the BlackBerry® Widget will open its default page. Modify the
“content” element in the config.xml file. Change this location to the web URL of the
avoidRecompile folder:
<?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 sample: Avoiding recompile</name>
<description> Enter your description </description>
<author href="http://www.yoursite.com/"
email="[email protected]">
Company Name – Developer Name
</author>
<content src="http://myDomain/avoidRecompile/index.html" />
<feature id="blackberry.system" />
</widget>
5. Grant the index.html file access to resources found under an external domain by adding the
following “access” element to the config.xml file:
<?xml version="1.0" encoding="utf-8" ?>
<widget xmlns="http://www.w3.org/ns/widgets"
6|Page
xmlns:rim="http://www.blackberry.com/ns/widgets"
version="1.0.0">
<name>Widget sample: Avoiding recompile</name>
<description> Enter your description </description>
<author href="http://www.yoursite.com/"
email="[email protected]">
Company Name – Developer Name
</author>
<content src="http://myDomain/avoidRecompile/index.html" />
<feature id="blackberry.system" />
<access uri="http://myDomain" subdomains="true">
</access>
</widget>
6. Create the following index.html file in the avoidRecompile folder:
<html>
<head>
<meta name="HandheldFriendly" content="True" />
<script type="text/JavaScript"
src="http://myDomain/avoidRecompile/scripts.js"></script>
</head>
<body>
<div>
<a href=”#” onclick="displayModel()">
Click to display your model number
</a>
</div>
</body>
</html>
Notice the path referencing the external JavaScript file is
“http://myDomain/avoidRecompile/script.js”.
7|Page
This index.html file displays a hyperlink that when clicked on will invoke a JavaScript method
named “displayModel”. This method is defined in the externally referenced file script.js.
7. Create the following scripts.js file in the avoidRecompile folder:
function displayModel() {
var model = blackberry.system.model;
alert('BlackBerry: ' + model);
The displayModel method uses the blackberry.system namespace from the BlackBerry®
Widget API to retrieve the model number for the BlackBerry® smartphone on which the application
is running.
8. You are now ready to build the widget. Create a ZIP file named tutorial.zip containing
only the config.xml file. Do not include the index.html or scripts.js files in this ZIP
file since we do not want them to be embedded resources.
9. The avoidRecompile folder should now contain the following files.
• config.xml
• index.html
• scripts.js
• tutorial.zip
10. Navigate to the BlackBerry Widget Packager folder and run the following command to
build the BlackBerry® widget.
bbwp.exe <path to avoidRecompile folder>\tutorial.zip
11. You should see the following output if successful:
[INFO] Parsing option parameters
[INFO] Parsing bbwp.properties
[INFO] Validating zip archive
[INFO] Widget packaging starts...
[INFO] Populating source codes...
8|Page
[INFO] Start compiling and building...
[INFO] Generating output files...
[INFO] Widget packaging is done.
12. A folder named “bin” will be created in the avoidRecompile folder containing the following
files:
§ avoidRecompile.alx
§ avoidRecompile.cod
§ avoidRecompile.csl
§ avoidRecompile.cso
§ avoidRecompile.jad
§ avoidRecompile.jar
§ avoidRecompile.rapc
13. Launch a BlackBerry® smartphone simulator version 5.0.0.252 or higher of the handheld
software. BlackBerry® Widgets depend on the BrowserField2 API that was introduced in version
5.0 of the Handheld OS.
9|Page
14. From the file menu, select the “Load Java program” menu item.
15. A popup window will open where you are prompted to select a COD file. Navigate to the
avoidRecompile\bin folder and select the avoidRecompile.cod file.
16. The BlackBerry® Widget will be loaded in the BlackBerry® smartphone simulator and can be
found in the “Downloads” folder. Launch your BlackBerry® Widget from the “Downloads”
folder.
10 | P a g e
17. The BlackBerry® widget will launch, and open the index.html file retrieved from the
http://myDomain/avoidRecompile location.
18. Click on the hyperlink displayed within the BlackBerry® Widget. A popup window will display
showing the model number of the BlackBerry® smartphone simulator.
11 | P a g e
19. At this point, you can change the contents of the index.html and scripts.js file found in
the avoidRecompile folder and they will be reflected in the widget without having to rebuild
and redeploy it to the BlackBerry® smartphone simulator. In order to see your changes, you may
have to re-open the page which may involve restarting the application.
20. Close the BlackBerry® Widget application.
21. Modify the scripts.js file found in the avoidRecompile folder to include logic that
displays the version number.
function displayModel() {
var model = blackberry.system.model;
var version = blackberry.system. softwareVersion;
alert('BlackBerry: ' + model + '(' + version + ')');
22. Save the scripts.js file.
23. Return to the BlackBerry® smartphone simulator, click on the “Click to display your model
number” hyperlink. Without having to rebuild and recompile your BlackBerry® Widget, the
changes made to JavaScript are now visible.
12 | P a g e
Notes
• This practice is recommended for making the development of BlackBerry® Widgets more
efficient. It is not recommended to follow this practice when deploying an actual
BlackBerry® Widget applications because the internal web resources would be vulnerable to
modification.
13 | P a g e
Links
BlackBerry Widgets Web Site:
http://www.blackberry.com/developers/widgets
BlackBerry Developers Web Site:
http://na.blackberry.com/eng/developers/
BlackBerry App World:
http://na.blackberry.com/eng/developers/appworld.jsp
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
