7. Configuring a Symbian Development Environment for PhoneGap
On the Symbian platform, PhoneGap applications are implemented as Web Runtime (WRT) widgets, a standard application type for Symbian devices. With WRT, a web application’s files are simply packaged into a compressed file before being deployed to mobile devices. There are some similarities here with the W3C widget specification described in Chapter 5, but since WRT widgets predate the specification, they are configured and packaged differently.
Symbian PhoneGap applications can be built on systems running Macintosh OS, Linux, or Microsoft Windows. Before getting started with Symbian development, you will need to install the PhoneGap framework using the instructions provided in Appendix A. In addition to the default PhoneGap files to build PhoneGap applications for Symbian, you will need to install the Nokia Web Tools as well as have access to the Make command-line utility.
Installing the Nokia Web Tools
Nokia offers a complete suite of tools for web development on the Symbian platform called Nokia Web Tools. Unfortunately, the most recent editions of the Nokia SDK removed support for testing WRT applications with a simulator. To be able to work with PhoneGap applications on Symbian, you will need to download version 1.2 of Nokia Web Tools located at www.tinyurl.com/7b7nyng. Do not download the latest version of the SDK.
Download the appropriate file for the operating system your development system is running, launch the installer, and then follow the prompts to complete the installation.
Note
The Nokia Web Tools SDK has an automatic update facility built in. Since we require version 1.2 of the SDK, you cannot allow the automatic update to happen.
Assuming you will want to use your favorite web content editor for PhoneGap development, most of the tools included in the download will likely go unused. The important tool for PhoneGap development is the web application simulator (called Web App Simulator on Windows and WebSDKSimulator on Macintosh OS), which will be described at the end of the chapter.
Installing the Make Utility
The default PhoneGap project for Symbian includes a makefile used by the Make utility to package the application for distribution to Symbian devices. Macintosh computers already include the appropriate files needed to process the makefile. For systems running Microsoft Windows, you will need to install additional software.
For Windows users, point your browser of choice to www.cygwin.com, and download the Cygwin installation file setup.exe. Launch the Cygwin installation program, and follow the prompts to install the software.
By default, Cygwin installs a minimal set of applications. At one point during the installation process, the installer will prompt you to select additional packages to install with Cygwin, as shown in Figure 7-1. For Symbian PhoneGap development, you will need to add the Make and Zip utilities to the list of programs installed during the installation.
Figure 7-1 Cygwin installation: Select Packages dialog
You can either browse the categories listed in the dialog to locate the particular utility or type the utility’s name in the search box on the dialog and press Enter. Once you have located the utility, click the refresh indicator on the line for the particular utility. This will change the option from Skip to the particular version of the utility being installed, as shown in Figure 7-1. Once both required utilities have been added to the installation, click the Next button to continue with the installation.
At the conclusion of the installation, you should have a Cygwin icon on the desktop. When you double-click the icon, a Windows command window will open and display a dollar sign prompt indicating it is waiting for you to type in a command. At this time, we won’t be using Cygwin, so type exit and press the Enter key to close the Cygwin window. We’ll get back to that later.
By default, Cygwin configures its start-up folder to point to the Cygwin installation’s home folder (c:cygwinhome in the default installation location). It’s likely your PhoneGap application projects will be in a different folder, so you will need to reconfigure Cygwin to use your source code folder as its root folder. This is accomplished by setting the HOME environment variable in Windows. To do this, open the Windows Control Panel, select System or right-click My Computer, and select Properties. In the System Properties application, click the Advanced System Settings tab, and then click the Environment Variables button on the bottom of the window.
Windows will display a dialog that lists the environment variables defined in the system. At the bottom of the dialog is the listing of system variables, the systemwide environment variables that affect all users. Click the New button in the System variables section of the dialog, and Windows will display a dialog similar to the one shown in Figure 7-2. Enter HOME in the Variable Name field, and for Variable Value enter the full path pointing to the folder you will be using for source code. Click the OK button to create the system variable, and then click OK again to close the Environment Variables dialog.
Figure 7-2 Adding a new Windows system variable
To test the changes you just made, open a Cygwin command prompt by double-clicking the Cygwin icon on the Windows desktop. At the command prompt, type ls, and then press the Enter key; if everything is configured correctly, you should see a directory listing of your source code folder.
Creating a Symbian PhoneGap Project
The PhoneGap download package contains the skeleton of a simple Symbian PhoneGap application you can use to create new PhoneGap projects. Figure 7-3 shows the file structure for the project. To create a new Symbian PhoneGap application, simply copy the Symbian folder from the PhoneGap installation location to your project’s source code folder, and then change the copied folder’s name to the name of the new application project.
Figure 7-3 PhoneGap sample application for Symbian
As shown in Figure 7-3, the project’s web content has been placed in the frameworkwww folder. Edit the index.html file and the other content in the folder to match the needs of your application.
Configuring Application Settings
Options for a Symbian WRT widget are defined in an XML-based configuration file called info.plist stored alongside the widget’s web content, as shown in Figure 7-3. A sample info.plist file is shown here:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Nokia//DTD PLIST 1.0//EN"
"http://www.nokia.com/DTDs/plist-1.0.dtd">
<plist version="1.0">
<dict>
<key>DisplayName</key>
<string>HelloWorld</string>
<key>Identifier</key>
<string>com.phonegapbook.helloworld</string>
<key>Version</key>
<string>1.0</string>
<key>AllowNetworkAccess</key>
<true/>
<key>MainHTML</key>
<string>index.html</string>
<key>MiniViewEnabled</key>
<false/>
</dict>
</plist>
The widget’s settings are defined as a dictionary of key/string pairs, as shown in the example. For each key defined within the file, there’s a corresponding string value that defines the value associated with the key:
• DisplayName: Displays the string value displayed along with the widget’s icon on the smartphone’s home screen
• Identifier: Unique identifier identifying the widget
• Version: The version number for the widget
• AllowNetworkAccess: Controls whether the widget is allowed to access network resources (remote servers and so on)
• MainHTML: Identifies the file name for the application’s start-up HTML page
• MiniViewEnabled: Controls whether the widget is designed to be a home page widget, an application that renders a content area on the device’s home screen
To change settings for a widget, simply open the file using your text or XML editor of choice, make the appropriate changes for your widget, and save the file.
Modifying HelloWorld3 for Symbian
The HelloWorld3 application from Chapter 2 won’t run on Symbian without modification. For a reason unknown to me, the onLoad event attribute for the HTML <body> tag doesn’t work correctly, so you have to embed the code that adds the deviceready event listener directly within the HTML header, as shown in the following example:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;
charset=utf-8">
<meta name="viewport" id="viewport"
content="width=device-width, height=device-height,
initial-scale=1.0, maximum-scale=1.0, user-scalable=no;"/>
<script type="text/javascript" charset="utf-8"
src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
document.addEventListener("deviceready", onDeviceReady,
false);
function onDeviceReady() {
//Get the appInfo DOM element
var element = document.getElementById('appInfo'),
//replace it with specific information about the device
//running the application
element.innerHTML = 'PhoneGap (version ' +
device.phonegap + ')<br />' + device.platform + ' ' +
device.name + ' (version ' + device.version + ').';
}
</script>
</head>
<body>
<h1>HelloWorld3</h1>
<p>This is a PhoneGap application that makes calls to the
PhoneGap APIs.</p>
<p id="appInfo">Waiting for PhoneGap Initialization to
complete</p>
</body>
</html>
Packaging Symbian PhoneGap Projects
When you’re ready to test the application in a simulator or deploy the application to a device, you must first package the application. Packaging is essentially zipping the application’s files into a zip archive and then changing the extension of the archive from .zip to .wgz. If you want, you can zip up the files manually and then change the file extension, but the Symbian PhoneGap project comes with a makefile that can be used to automate the packaging process.
Note
When using a terminal window to navigate around in a file system, use the cd command to change directories and the ls command to list a folder’s contents.
On Macintosh computers, open a terminal window; then navigate to the project’s root folder. On Windows computers, launch Cygwin; then navigate to the project’s root folder. Type make and press Enter to start the process; the terminal window will display a series of messages as the application is packaged, as shown in Figure 7-4. As you can see from the figure, the makefile first consolidates many of the PhoneGap JavaScript libraries into a single file called phonegap.js, creates a zip file containing the widget’s web content, and then renames the file to the appropriate .wgz extension.
Figure 7-4 Packaging a Symbian PhoneGap application using Make
At this point, the PhoneGap application has been packaged into a file called app.wgz and can be loaded into the Symbian Web App Simulator or deployed to a real device. To change the file name for the packaged application, edit the makefile and change any references to app.wgz to the appropriate file name for your application.
Testing Symbian PhoneGap Applications
To test PhoneGap widgets for Symbian, launch the Symbian Web Application Simulator (the simulator application icon is labeled Web App Simulator on Windows and WebSDKSimulator on Macintosh OS). When the simulator launches, it will open two windows on the screen; the first is the toolbar (shown in Figure 7-5), a sort of simulator controller that allows you to poke and prod at the simulator while it’s running, and the second is the device simulator window (shown in Figure 7-6). You will use the toolbar when loading widgets into the simulator and when debugging widgets.
Figure 7-5 Symbian Web App Simulator toolbar
Figure 7-6 Symbian Web App Simulator
Note
If the option for the web simulator is missing, check to make sure you didn’t inadvertently install a version of the Nokia Web Tools SDK newer than version 1.2.
To test a PhoneGap widget, launch the simulator, click the File button on the toolbar, navigate to the folder where the widget’s .wgz file is located, and open the file. The widget will load in the simulator and then display a screen similar to the one shown in Figure 7-6.
Notice that the HelloWorld3 application isn’t displaying as much device information as with the same application on other platforms. It’s clear that the PhoneGap development team has some work to do on Symbian.
The simulator represents a real device, and touch interactions with the device screen are performed using the mouse. Use the Location and Accelerator buttons on the toolbar to simulate a particular GPS location and control the perceived orientation of the device. Use the Events button to control events affecting the simulated device such as adding or removing power or a memory card, receiving SMS or MMS messages, and more.
The toolbar also provides capabilities that help with debugging widgets. Click the Web Inspector button to open the Web Inspector, as shown in Figure 7-7. The Web Inspector is essentially the Eclipse debug window with styling to match the other Nokia tools. You can click the different buttons across the top of the window to inspect and interact with different aspects of the widget currently running within the simulator including setting breakpoints, setting watches, evaluating variables, and more.
Figure 7-7 Symbian Web Inspector