7. Android Development with Cordova
Google offers developers a robust suite of tools they can use to develop applications for the Android platform. Even though the Cordova CLI takes care of most of the process of creating, managing, and testing applications, there will be times when you want to have more control over the process. Even though the CLI can launch a Cordova application in the Android platform emulator, when you encounter problems with an application, and you want to know more about what’s going on, you’ll need to use the development tools that come with the Android Development Tools (ADT).
Instructions for using the CLI to create and manage Android projects can be found in Chapter 4, “Using the Cordova Command-Line Interface.” In this chapter, I show you how to configure ADT and use it to help you test and debug your Cordova applications.
If you’re not developing for Android or you plan on using only the CLI and/or PhoneGap Build to build and test your applications, then you can likely skip this chapter. However, there are some cool tools included with ADT, so what you’ll learn in this chapter should simplify your Android application testing and debugging efforts.
Working with the Android Development Tools
In Chapter 3, I briefly showed how to install the Android Development Tools, but I really didn’t cover the topic too deeply or show you how to use them. By default, ADT ships with a preconfigured version of the open-source Eclipse IDE. You can use this IDE to edit, compile, run, and debug Android Java applications; you can learn more about and download ADT at the Android Developer web site at http://developer.android.com/sdk/index.html.
If you’re already using Eclipse for other development work, you can add ADT to an existing Eclipse installation using instructions found at http://developer.android.com/sdk/installing/installing-adt.html. The process is pretty easy and doesn’t take a lot of time. Be sure to check the system requirements to make sure the version of Eclipse you are using is compatible before attempting to add ADT. Google is really good about keeping up with Eclipse and supports a wide range of Eclipse versions.
ADT includes command-line tools a developer can use to interact with a device or emulator from the command line. This mechanism is one of the tools the Cordova CLI uses to interact with the Android platform. I’m not going to spend any time on the command-line tools here, though.
Using the ADT IDE
To start the ADT IDE, navigate to the folder where you extracted the Android SDK and launch the Eclipse application located in the eclipse folder. The application will be called eclipse on Macintosh OS and Eclipse.exe on Microsoft Windows. When you first start ADT, you will see a screen similar to the one shown in Figure 7.1.
Dealing with ADT IDE Memory Problems
When I first started working with ADT on my Windows laptop, I ran into a lot of problems with the IDE crashing whenever I tried to open Cordova project files or add plugins to Eclipse. After many hours of troubleshooting and searching on the web, I finally located the problem. By default, the Eclipse instance in ADT is configured to utilize a limited amount of system memory; ADT was crashing simply because it didn’t have the memory it needed to do the things it wanted to do.
There are several ways to increase the amount of memory consumed by different parts of Eclipse. You can pass memory configuration settings as command-line options to Eclipse when you start it, or you can make some simple updates to ADT’s eclipse.ini file. I chose to use the latter approach. I’m not sure what the exact settings need to be; your mileage will vary, but I simply opened up the eclipse.ini file and cranked up the memory settings highlighted in bold in Listing 7.1. If you have problems with random crashes in ADT, increase those memory settings and see if they go away.
Listing 7.1 Contents of the Android Development Tools eclipse.ini File
-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20120913-144807
-product
com.android.ide.eclipse.adt.package.product
--launcher.XXMaxPermSize
512M
-showsplash
com.android.ide.eclipse.adt.package.product
--launcher.XXMaxPermSize
512m
--launcher.defaultAction
openFile
-vmargs
-XX:MaxPermSize=512m
-Dosgi.requiredJavaVersion=1.6
-Xms512m
-Xmx1024m
-Declipse.buildId=v22.0.1-685705
Editing Cordova Application Content Files
Android applications are built using Java, but developers can also code portions of their applications in C or C++. Since Android supports only those limited options for application development, ADT does not include tools specifically designed to help with debugging web applications such as those that run within the Cordova container. So, you won’t be able to step through an application’s JavaScript code, set breakpoints, configure watch expressions, and so on, within the ADT IDE. To debug Android applications, you need to use the debugging approaches highlighted in Chapter 6, “The Mechanics of Cordova Development.” However, these debugging approaches can be enhanced using some of the tools described later in this chapter.
Note
During the book’s technical review process, Damien pointed out that Google offers a Chrome plugin that enables remote debugging of Android Cordova applications. Unfortunately, there was no time available to add content about this feature to the manuscript, so I will read up on this capability and post updated content to my personal blog at www.johnwargo.com and the book’s website at www.cordovaprogramming.com.
Although the CLI is optimized for editing a Cordova application’s web application source code in the www folder rather than within one of Cordova project’s platform folders, you will likely use an external web content editor such as Adobe Dreamweaver, Adobe Brackets, or some other tool. Since ADT is configured for editing Java and C applications, it doesn’t include editors to help with editing the HTML, CSS, and JavaScript files your Cordova application will use. Because of this limitation, if you want to use Eclipse to edit your Cordova application content, you need to install web content editing capabilities into ADT. The default tools for web content editing in Eclipse are from the Eclipse Web Developer Tools Project, and you can install them in ADT in a few minutes.
Within ADT, open the Help menu and select Install New Software. ADT displays the Install wizard, shown in Figure 7.2. In the Work With dropdown field shown in the figure, select the Juno option. Juno is the version of Eclipse that ADT is currently using—you may find yourself using a newer version, so look for the entry that points to http://download.eclipse.org/releases/ instead of http://download.eclipse.org/eclipse/updates/. After you make the selection, the list of options will populate: scroll down and select Eclipse Web Developer Tools, as highlighted in the figure, and step through the wizard to complete the installation.
Importing the Cordova Project
Assuming you followed the instructions in Chapter 4 to create an Android project, you should have a Cordova application project in a folder structure similar to the one shown in Figure 7.3. If you haven’t already copied over the project’s web content from the www folder to the Android project’s folder, be sure to issue the Cordova prepare command now to complete that process:
cordova prepare android
With the project folder in place, you must import the project into ADT before you can work with it. To start the import process, in the ADT IDE open the File menu, then select Import. The ADT IDE displays the Import wizard, shown in Figure 7.4. Expand the Android option and select Existing Android Code Into Workspace, as shown in the figure, then click the Next button.
ADT displays the next page in the Wizard, shown in Figure 7.5. In this dialog, you need to populate the Root Directory field with the location where the Cordova project’s Android project files are located. Click the Browse button and navigate to the Android folder, highlighted in Figure 7.3, then click the OK button. The Wizard should automatically add the HelloCordova project to the list of available projects, as shown in Figure 7.5.
When you click the Finish button, ADT should complete the import process and open the imported project into the IDE, as shown in Figure 7.6. Since the Cordova project consists of both a native Java Android application plus the web content that executes within the application, you will see a blending of a default Android project structure plus the Cordova www folder discussed in previous chapters.
Warning
Any changes you make to the web application content stored in the Android project’s www folder will not be propagated back to the Cordova project’s main www folder. The CLI doesn’t currently have a mechanism to do so (who knows, perhaps there will be one by the time you read this). If, during your debugging of the application, you make changes to the web application in ADT, you need to manually copy those changes back to the Cordova project’s root www folder.
To make this easier, you could add an External Tool to ADT that triggers a copy of the web content files back to the Cordova project’s www folder.
Running Your Cordova Application
Now that the Cordova project has been imported, you probably want to run it to see how it works. The ADT IDE doesn’t have any Android run configurations defined by default, so you have to add at least one before you begin. In the ADT IDE, open the Run menu and select Run Configurations. The IDE displays a dialog similar to the one shown in Figure 7.7.
In the dialog, select Android Applications, then click the New button, highlighted in the figure. Define the settings for the Run Configuration, assigning an application to it, and determine parameters around how it launches one or more Android device emulators when it runs. If you don’t have any emulator devices defined (by default, you won’t), click the Manage button to open the Android Virtual Device (AVD) Manager to create and manage the system’s emulator definitions.
With one or more Run Configurations defined, you can click the Run button, shown at the bottom of the figure, to launch the emulator and run your application. You can also close this dialog, then run the application on the selected Android emulator by making the appropriate selection from the Run menu or by right-clicking on the application project in the Project Explorer (shown on the left side of Figure 7.6), selecting Run As, then selecting Android Application.
ADT will launch the selected Android emulator (this will take a very long time—be patient, the Android emulators are not known for being fast), then compile, package, and deploy the Cordova application to the emulator.
ADT Debugging Tools
As the ADT IDE processed everything and launched your Cordova application, you may have noticed a lot of information scrolling by on certain parts of the screen. ADT includes utilities that allow a developer to monitor activity on an emulator or physical device. This functionality is provided by the Console and LogCat views in the IDE. LogCat is part of the IDE but can also run through the command line or as a standalone utility.
ADT opens the LogCat window automatically, but if it gets closed for any reason, you can open it by opening the Window menu, selecting Show View, then selecting Other. The ADT IDE will display a dialog similar to the one shown in Figure 7.8. Expand the Android option to see the list of views available to you. Select LogCat (not the deprecated one shown in the figure) and click the OK button to open the view.
The console window shows messages generated by the ADT IDE as it prepares the Cordova application and deploys it to the emulator. You can see an example of the console’s output in Figure 7.9. If the ADT IDE has trouble building, packaging, or deploying your application, it lets you know in the console window. If you’ve launched the app in the emulator, but nothing seems to be happening, take a look at the console.
LogCat, on the other hand, interacts directly with an Android emulator or physical device (I show you how to debug on a physical device a little later). The LogCat window shows a multitude of messages as the emulator completes its startup process and as you interact with any part of the Android OS. Look to LogCat for any error messages when you’re having trouble with an emulator or device or a running an Android application.
Also, if you remember from Chapter 6, I mentioned you could have your Cordova applications write information to the console object as your application runs; on Android, those console object messages are displayed within the LogCat window. If you take a look at Figure 7.10, you’ll see LogCat displaying the output from the sample application highlighted in Listing 6.2.
In the LogCat window, you can filter messages based on their type. Notice the debug button shown on the upper-right corner of Figure 7.10; when you click the button, a drop-down appears, allowing you to select which level of message (verbose, debug, info, warning, and error) are displayed in the view.
Debugging Outside of the ADT IDE
If you don’t want to use the ADT IDE, you can run the ADT debugging tools outside of the IDE. The standalone version of LogCat and associated tools can be found in the Android Debug Monitor (ADM) utility, which is started by navigating to the Android SDK’s Tools folder and executing the monitor.bat (on Windows) or monitor (on Macintosh OS) application.
When the ADM launches, it displays a window similar to the one shown in Figure 7.11. I’m not going to cover all of the options available here, but you can see that there’s a lot of information available. The lower half of the application’s window displays the same LogCat window from the ADT IDE. In the figure, you can see that I’ve connected the ADM to an Android device emulator; I show you how to connect to a physical device a little later.
You should spend some time poking around within the ADM—there’s a lot of power in what it provides developers.
Grabbing a Screenshot
While not critical for developers, it’s sometimes useful to be able to pull a screenshot off of an emulator or physical device. If you take a look at Figure 7.11, within the Device area in the upper-left corner of the ADM, you will see a little camera icon. With a device connected, you can click that button and grab a screen capture from the connected device. When you click the button, the ADM displays a screen similar to the one shown in Figure 7.12 (I’ve cropped the image to reduce the amount of space used for the figure). In this example, you’re seeing a portion of the screen from my Google Nexus 7 tablet.
You can use the buttons along the top of the screen to refresh, rotate, save and copy the image. Using this feature is a quick and simple way to grab a screen image for documentation or support purposes and frees you from having to perform the screen capture on the device and transfer it to your PC.
Debugging on a Physical Device
The ADM can also interact with a physical device just as it can with a device emulator. Initial testing of an application can be done on an emulator, but before any application is released, it should be tested on a representative sample of the physical devices the application is expected to run on.
To use a physical device with ADM, you must connect the device to the computer system running ADM using a USB cable. Before you can do that, you must enable USB debugging on the device. The way you enable this setting varies depending on which type of Android device you are using. On some devices, enabling developer options is accomplished by simply opening the on-device Android settings application and making some selections. On other devices, it’s a little harder. You’re just going to have to figure this one out on your own, sorry.
In order to be able to test on a live device, your computer system must be able to recognize an Android device when it’s connected to the system via a USB cable. If you connect a device and it’s not recognized by the system, you must resolve any connectivity issues before continuing.
In my testing on Windows, I had to manually install the Google USB driver from the SDK Manager and then, in Windows Device Manager, force the installation of the right driver. You can read about the steps at www.johnwargo.com/index.php/mobile-development/nexus-7-setup-on-windows1.html.
For Samsung devices, you may need to download and install the USB drivers separately before the device is picked up correctly by Windows. See http://developer.samsung.com/android/tools-sdks/Samsung-Andorid-USB-Driver-for-Windows for additional information.
For a Google Nexus 7 tablet, for example, you have to take some special steps before you can even access the developer settings. To enable developer mode on the Nexus 7, you have to open the settings application and select About Tablet (it is the very last item on the list of options on the Settings page). On the About Tablet page, scroll down until you see the Build number item in the list. Tap on the Build number item seven times to enable the developer options on the device. As you tap, Android will pop up a little window indicating how many more times you need to tap to enable developer mode.
With that process completed, when you open the Settings application, you should be able to scroll down to the bottom of the list of options and see a Developer options option available, as shown in Figure 7.13.
Click on Developer options and you will see a screen similar to the one shown in Figure 7.14; from here you can enable USB debugging, as shown at the bottom of the figure.
With USB debugging enabled, launch the ADM, then connect the Android device to the computer system using a USB cable. After the necessary device drivers initialize (see the preceding warning for information about how to deal with driver issues), ADM should connect to your device and show the connected device in its list of connected devices, as shown in Figure 7.15.
In ADM, you have access to many of the same capabilities with a physical device as you do with a device emulator, but there are differences. Refer to the Android documentation for more information about the capabilities of ADM with a physical device. ADM is a good way to pull files from or push files to a device for testing purposes. However, much of the file structure is protected, so you won’t be able to access all file locations.
Wrap-Up
In this chapter, I showed you how to use the free tools available from Google that help simplify Android development for Cordova. Although the Android tools do not directly assist with debugging Cordova applications, by using these tools, you can more easily determine what’s going on within your Cordova applications.