8. BlackBerry 10 Development with Cordova
Of all of the platforms that Cordova supports, the BlackBerry 10 platform most closely aligns with the Cordova approach. The hybrid application approach has been a core application type for BlackBerry for quite some time, and for BlackBerry devices, Cordova is built on top of it. In this chapter, I show you how to use the BlackBerry command-line tools to test and debug BlackBerry Cordova applications.
One of the cool things about BlackBerry development is that the BlackBerry SDK automatically integrates a web inspector like weinre into the simulator; I show you how to use it here.
The Cordova team announced that it is dropping support for legacy BlackBerry devices (devices running BlackBerry Device Software 7 and earlier), so I cover only BlackBerry 10 here. To work with legacy BlackBerry devices, you need to use Cordova version 2.9 or earlier.
Configuring Your Environment for BlackBerry Development
Before you can get started with BlackBerry development for Cordova, you must first configure your development environment. I showed you how to install the BlackBerry Native SDK (NDK) in Chapter 3, but I omitted some BlackBerry-specific configuration details from that chapter; I describe them here.
As a reminder, before you can build BlackBerry applications that will run on BlackBerry devices, you must first obtain and install a set of free signing keys from BlackBerry. Open your browser of choice and point it to https://www.blackberry.com/SignedKeys to request a set of keys. You eventually will receive a series of emails from BlackBerry, extract the key files to a location on your system’s hard drive, and follow the instructions in the emails to activate your keys.
You need to register the keys using the instructions found at https://developer.blackberry.com/html5/documentation/signing_setup_bb10_apps_2008396_11.html. You can register the keys using the Momentics IDE included with the SDK installation, or you can use the command line by issuing the following command:
blackberry-signer -register -csjpin <csj pin>
-storepass <KeystorePassword> <client-RDK-xxxxxx.csj file>
<client-PBDT-xxxxx.csj file>
In this example, you replace the items in brackets with the following information:
<csjpin>: The PIN you provided BlackBerry when you requested the signing keys.
<KeystorePassword>: The password you want used to secure the keystore created during this process. This is the password you will use to unlock your signing keys whenever you sign a BlackBerry application.
<client-RDK-xxxxxx.csj file>: The path pointing to the client-RDK-xxxxxx.csj file you received from BlackBerry.
<client-PBDT-xxxxx.csj file>: The path pointing to the client-PBDT-xxxxx.csj file you received from BlackBerry.
For the NDK, the files you need are located in the BlackBerry NDK installation folder. For my development system, I installed the NDK in c:bndk, so the blackberry-signer file is located in C:bndkhost_10_1_0_132win32x86usrin. So, I opened a terminal window and navigated to that folder, then issued the following command:
blackberry-signer -register -csjpin 987456321
-storepass my_keystore_password c:devkeysclient-RDK-123456.csj
client-PBDT-12345.csj
If this works correctly, the system should respond with the following:
Info: CSK file created.
Info: Developer certificate created in
C:UsersjwargoAppDataLocalResearch In Motionauthor.p12
Info: Successfully registered with server.
Info: Successfully registered with server.
Additional steps must be completed before you can test Cordova applications on a physical BlackBerry 10 device, but I cover those later in the chapter.
As shown in Chapter 3, “Installing the Cordova Command-Line Interface,” you can add support for a particular mobile device platform to a Cordova project using the following command:
cordova platform add platform_name
When adding support for BlackBerry to an existing project, you would use the following:
cordova platform add blackberry10
However, when you run the command, you may receive an error message similar to the following:
blackberry-nativepackager cannot be found on the path. Aborting.
This happens because one or more of the tools you need to add BlackBerry support to a Cordova project or to use the BlackBerry native SDK cannot be found on the system path. Before you can use any of the BlackBerry 10 NDK command-line tools, you must first add some BlackBerry 10 NDK configuration information to your environment’s configuration. The easiest way to do this is to execute the bbndk-env command that’s included with the NDK. The command updates your system path with some additional folders and sets several environment variables the BlackBerry 10 NDK needs to find its files, as shown in Figure 8.1.
On Windows, I simply added the BlackBerry 10 NDK installation folder (c:bndk) to the Windows system path. Then, whenever I open a terminal window to work on a BlackBerry project, I simply execute the bbndk-env.bat file before issuing any commands that affect the BlackBerry 10 portion of a project. You could automate this by adding the call to the batch file to the system’s autoexec.bat file, but I didn’t take the time to do this.
On Macintosh OS, you need to run a shell script called bbndk-env.sh to set up the BlackBerry 10 development environment. You can add the BlackBerry 10 NDK installation path to the system path, then execute the script manually as needed, or you can configure your system to execute the script when opening new terminal windows.
Now when you add the BlackBerry 10 platform to your Cordova project, the process should run properly and not return any errors to the terminal window.
Configuring a BlackBerry Cordova Project
A BlackBerry Cordova project is configured through the BlackBerry 10 project’s config.xml file, shown in Listing 8.1. A BlackBerry hybrid application conforms to the WWC Widget Specification (www.w3.org/TR/widgets), and the config.xml is the standard file used to configure a widget. To access a BlackBerry project’s config.xml file, navigate to the Cordova project’s platformslackberrywww folder and open the file with your XML or text editor of choice.
I’m not going to describe all of the possible settings for the BlackBerry config.xml; you can find detailed documentation from BlackBerry at https://developer.blackberry.com/html5/documentation/config_doc_elements.html. I do, however, describe some of the options, but first take a look at the file in Listing 8.1.
Listing 8.1 BlackBerry 10 Project Config.XML
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!--
Widget Configuration Reference:
http://docs.blackberry.com/en/developers/deliverables/15274/
-->
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:rim=http://www.blackberry.com/ns/widgets
version="1.0.0.1" id="default.app.id">
<name>WebWorks Application</name>
<author>John M. Wargo</author>
<description>
A sample Apache Cordova application that responds to the
deviceready event.
</description>
<license href="http://opensource.org/licenses/alphabetical">
</license>
<!-- Expose access to all URIs, including the file and http protocols -->
<access subdomains="true" uri="file:///store/home" />
<access subdomains="true" uri="file:///SDCard" />
<access subdomains="true" uri="*" />
<icon src="res/icon/blackberry/icon-80.png" />
<rim:splash src="res/screen/blackberry/splash-1280x768.png" />
<rim:splash src="res/screen/blackberry/splash-720x720.png" />
<rim:splash src="res/screen/blackberry/splash-768x1280.png" />
<content src="index.html" />
<rim:permissions>
<rim:permit>use_camera</rim:permit>
<rim:permit>read_device_identifying_information</rim:permit>
<rim:permit>access_shared</rim:permit>
<rim:permit>read_geolocation</rim:permit>
<rim:permit>record_audio</rim:permit>
<rim:permit>access_pimdomain_contacts</rim:permit>
</rim:permissions>
</widget>
The config.xml name, author, and description elements describe the application to the BlackBerry user. The name element defines the name that appears on the device home screen and the application list. Author and description are not critical but are useful to set. The author is displayed in application security prompts (you can see an example in Figure 8.4), and the description should appear in the application details screen within device options.
The content element defines the name of the web content file that is launched when the container starts. This value is set to index.html by default, but you can change it to any valid src reference. If your web application’s main page is in a file called rabbit.html, you would set the src value for content to rabbit.html, as in the following example:
<content src="rabbit.html" />
The most important aspect of the config.xml is the rim:permissions element; it is used to list the different application permissions the application requires. If your application uses a restricted capability and you don’t have it listed as a rim:permit element, then the part of the application that leverages that capability will not function. Your application’s not going to tell you what’s wrong—it just won’t work correctly.
There’s a lot you can do with the settings in the config.xml, but it’s way beyond the scope of this book to cover all options. Refer to the BlackBerry developer documentation for more information on this topic.
Defining BlackBerry 10 Targets
Before you can test and debug a BlackBerry 10 Cordova application using a device simulator or a physical device, you must first configure your Cordova development environment for each of the devices you will use (whether they are a simulator or a physical device); each one is referred to as a target. Fortunately, the targets you define are global to your Cordova configuration, so you only have to create them once, and you can use them for any Cordova project you work with.
If you take a look at the .cordova folder in your default user’s folder, you will see a file called blackberry10.json. This file contains the global list of targets defined for your Cordova development environment. Initially, it points to an empty list of target objects:
{
"targets": {}
}
As you’ll see in the sections that follow, as you add targets to the system, this file gets updated with the appropriate settings for each. The Cordova CLI emulate and run commands use this information to locate the appropriate targets when executing Cordova applications.
The files you need to create BlackBerry targets are installed into your Cordova project when you add support for BlackBerry 10. The sections that follow illustrate how to define targets for the BlackBerry 10 simulator as well as a physical BlackBerry 10 device.
Defining a BlackBerry 10 Simulator Target
To define a BlackBerry 10 simulator target, first launch the appropriate device simulator, then navigate to the project’s platforms/blackberry10/cordova folder and execute the following command:
target add target_name ip_addr –t simulator
As you can see, the process needs to know the IP address of the simulator; fortunately, the simulator displays its IP address at the bottom of the simulator window, as shown in Figure 8.2.
Assuming the simulator’s IP address is 192.168.215.128 and the Cordova project was created on Windows in c:usersjwargodev est, you would open a terminal window, then navigate to c:usersjwargodev estplatformslackberry10cordova and issue the following command:
target add bb10-sim 192.168.216.128 –t simulator
After the completion of that command, the blackberry10.json file is updated to include the settings for the target:
{
"targets": {
"z10-sim": {
"ip": "192.168.216.128",
"type": "simulator"
}
},
"defaultTarget": "z10-sim"
}
When you start the BlackBerry 10 device simulator, you can select which device type the simulator simulates. You can define separate targets for each simulator type and define the default simulator to use via the defaultTarget variable defined in the blackberry10.json file.
Defining a BlackBerry 10 Device Target
To define a BlackBerry 10 target using a physical device, the process is similar to what was shown in the previous section, but additional setup steps must be completed before you can create the target.
To test and debug your BlackBerry 10 Cordova applications, you must first enable debug Development Mode on the device. To do this, open the device’s Settings application, then open the Security and Privacy section of the application. At the bottom of the list of options displayed, select the Development Mode option. The device will open a screen similar to the one shown in Figure 8.3. At the top of the screen, set the Use Development Mode option to On, as shown in the figure. You may also want to set the IP address for the device. If you will be testing on multiple devices, you need to make sure that the IP addresses are unique across devices and define a separate target for each device.
With those settings in place and the device physically connected to the computer system using a USB cable, you can now create the target. The settings for a physical device are a little different as the current version of the BlackBerry command line tools requires the device password as well as the device PIN. In Cordova 3.1, the BlackBerry development team will be implementing PIN detection to their command line tools.
Assuming the Cordova project was created on Windows in c:usersjwargodev est, you would open a terminal window then navigate to c:usersjwargodev estplatformslackberry10cordova and issue the following command:
target add target_name ip_address –t device –p device_password –pin device_pin
For my particular configuration, the command is
target add z10-device 169.254.254.253 –t device –p abcdef –pin 2AB09876
which adds settings for the device to the system’s blackberry10.json file, as shown here:
{
"targets": {
"z10-sim": {
"ip": "192.168.216.128",
"type": "simulator"
},
"z10-device": {
"ip": "169.254.254.253",
"type": "device",
"password": "abcdef",
"pin": "2AB09876"
}
},
"defaultTarget": "z10-sim"
}
To change the configuration so the physical device is the default target, issue the following command in the terminal window:
target default z10-device
To see a list of the defined targets on the system, issue the following command:
target
The system will respond with the list of targets, as shown here:
z10-sim
* z10-device
The asterisk marks the default target.
Debugging on a Device Simulator
Cordova applications for BlackBerry don’t use the BlackBerry Momentics IDE for managing applications; instead, everything is done via the Cordova CLI. To run a Cordova application in the BlackBerry 10 simulator, first start the simulator, then navigate to the Cordova project folder and issue the following command:
cordova emulate blackberry10
The CLI will build the BlackBerry 10 project, load it into the simulator, then launch the application. You can also navigate to the project’s platforms/blackberry10/cordova folder and run the application using the run command found in that folder. The simulator must be running before you issue the command—the CLI won’t launch it for you. The process of building and deploying the Cordova application takes quite some time, so be patient.
The default Cordova project used in this example enables security settings for all of the available plugins, although none are enabled in this project. Because BlackBerry is a secure platform, when the application first launches, you are prompted to allow access to the different Cordova APIs, as shown in Figure 8.4. These settings are described in “Configuring a BlackBerry Cordova Project,” earlier in the chapter. Just click the OK button to continue.
BlackBerry 10 Cordova projects enable the BlackBerry Web Inspector by default. When a Cordova application launches in the simulator, it lets you know if Web Inspector is enabled, as shown in Figure 8.5.
To disable the Web Inspector, you must build the application in release mode. You can do this by opening a terminal window, navigating to the Cordova project’s platformslackberry10cordova folder, and issuing the following command:
build --release --keystorepass your_keystore_password
I show you how to use the Web Inspector a little later. When you click OK, the application opens and displays its web content, as shown in Figure 8.6.
At this point, the application is running on the simulator, and you can interact with the application as you would on a physical device.
Note
For some reason, the BlackBerry 10 device simulator has difficulty rendering the background image in the default Cordova HelloWorld application. I experienced this on two different computers but didn’t experience the same issue on a physical device. All the more reason to use the simulator for initial testing, but do all final testing on physical devices.
Using the BlackBerry Simulator Controller
Some things happen on a physical device that you can’t easily map to a simulator; examples are determining the device location, responding to phone calls, orientation changes, and so on. To help developers manage such issues while working with a simulator, the BlackBerry simulator includes a separate controller program you can use to manipulate the simulator as its running. The controller is installed alongside the device simulator as a separate icon; double-click the icon to the program, and it opens in a window similar to the one shown in Figure 8.7.
The controller automatically connects to a running simulator; otherwise, you can use options in the Connection menu to disconnect and connect manually. Use the Device menu to access the available options for manipulating the simulator. For example, there’s an option for setting GPS position; when you select that option, a new window appears, as shown in Figure 8.8.
Set the appropriate location information and click the Apply button to apply the settings to the simulator. If your Cordova application that’s running in the simulator were watching the simulated device’s location, it would automatically register the change and react as you’ve coded within your application.
The Controller can do a lot more for you as you work with your BlackBerry Cordova applications. Take a few moments and poke around in the Device menu to see what other options are available to you.
Using the BlackBerry Web Inspector
Since the hybrid application approach is a standard option for BlackBerry development, debugging Cordova applications is much easier than on some other platforms. The built-in tools allow a Cordova developer to more easily understand what’s going on within the web application running in the Cordova native container. The Web Inspector provides critical capabilities in this area and works with the device simulator as well as physical devices.
As described previously, by default Web Inspector is enabled for Cordova applications built using the Cordova CLI. When a Cordova application with Web Inspector enabled runs in the BlackBerry 10 Simulator, you can fire up a browser and watch the application as it runs within the container, highlighting HTML elements, evaluating expressions, stepping through code, and more. To demonstrate, I created a simple Cordova application with a little bit of JavaScript code and launched it within the simulator. When the application runs in the simulator, it renders the screen shown in Figure 8.9 (cropped for brevity’s sake).
To use the Web Inspector to debug this application, open the Google Chrome browser and enter the following URL:
http://device_IP_Address:1337
The device_IP_Address refers to the IP address of the device simulator or physical device running the application. So, for the simulator shown in the figure, use the following:
When you press enter, the browser connects to the browser running on the device and opens a screen similar to the one shown in Figure 8.10. To debug a Cordova application, select the option highlighted in the figure; the web resource at local:///index.html is the start page for the web application running within the Cordova container. The other options shown in the figure are for the browser and browser chrome running on the device.
After you make that selection, the browser should open a page similar to the one shown in Figure 8.11.
Using the different options shown across the top of the browser page shown in Figure 8.11, you have access to a tremendous amount of information about the application. For Cordova application debugging, there are a couple of features here that are quite useful.
If you click on the Sources icon (located in the list of icons across the top of the page shown in Figure 8.11), you are presented with the page shown in Figure 8.12. The Web Inspector disables debugging by default, but you can turn it on here, as shown in the figure. Enable the appropriate radio button on the page and click the Enable Debugging button to continue.
Next, the Web Inspector displays a list of source files for your application; you can select any of them to open a debug session using that source file. In Figure 8.13, I selected the Cordova application’s index.html file because, for this simple example, that’s where all of my code is located.
In this interface, I can set breakpoints (as I have in line 18, shown in Figure 8.13), define watch expressions, view the call stack, inspect variables, and more.
In this example, I clicked the Click Me button shown in Figure 8.9 and stepped through a few lines of code. When the Web Inspector hits a breakpoint, you can step through your code in different ways using the buttons highlighted at the top right of Figure 8.13. At this point, the Web Inspector works like any other debugger you’ve worked with in the past.
To round out this example, Figure 8.14 shows the console page, which displays the output of the code. Here I can view the output of calls to the console object. Unlike the Apple debugger, the Web Inspector uses colored icons for warning and error log entries and even color-codes the error output so it can be more easily located during a debugging session.
As you can see, the BlackBerry Web Inspector is a pretty powerful tool for debugging Cordova applications.
Debugging on a Physical Device
When working with a physical device, the Web Inspector capabilities are still supported, so the information in the previous section still applies. In general, to run the application on a device, you must connect the device to the computer, then navigate to the Cordova project folder and issue a CLI command. You can connect the device via USB cable, or if the device is on the same network as your development computer, you can connect over Wi-Fi as well.
The first time you run the application on a device, you have to generate a debug token and deploy it to the device. To learn more about Debug Tokens on BlackBerry, refer to https://developer.blackberry.com/html5/documentation/runnning_unsigned_apps_using_a_debug_token_1866987_11.html. So, the first time you run an application on a BlackBerry device, you should use the following command:
cordova run blackberry10 -k keystore_password
This command instructs the CLI to create the debug token, deploy it to the device, then package the application and deploy it to the device as well. If everything works correctly, after quite a long wait (it really is quite a long wait), you should see the Cordova application running on the device.
On subsequent runs, after the debug token has been installed on the device, you can run the application on a device using following command:
cordova run blackberry10
If you have multiple targets defined, you can launch the application on a specific target by issuing the following command:
cordova run blackberry10 --target target_name
To run the application on whichever device is currently connected, issue the following command:
cordova run blackberry10 --device
Wrap-Up
This chapter has demonstrated how to use the command-line tools provided by BlackBerry to run and debug Cordova applications on both a device simulator and physical device. The broad spectrum of available tools provided by BlackBerry provides the Cordova developer with some additional capabilities not available on other platforms.