4. Configuring a bada Development Environment for PhoneGap

Bada is a mobile device operating system released by Samsung in 2010. Devices for this OS are not available in the United States today, but bada devices are currently popular in Europe and Asia. The current version of the bada files for PhoneGap do not support the currently version of the bada SDK; instead, it requires an older version that is not currently available for download. You will have to already have a version of the bada SDK earlier than version 2.0 installed in order to build PhoneGap applications for bada. As the PhoneGap project team adds support for the current version of the bada SDK, an updated version of this chapter will be available on the book’s web site at www.phonegapessentials.com.

The bada development tools will run only on computers running Microsoft Windows, so you’ll need to have a Windows PC or a Macintosh running a Windows virtual machine (VM) to install the tools. Before getting started with the bada SDK, you will need to install the PhoneGap framework, but unfortunately as of the time of this writing, the PhoneGap files installed using the instructions provided in Appendix A don’t contain the project files you need to build PhoneGap applications for bada. It’s possible that by the time you read this, the PhoneGap files will be updated to include the complete set of bada files. In the meantime, additional instructions are provided within this chapter for downloading and installing the correct files for PhoneGap bada development.

The free bada development tools are implemented using the Eclipse IDE, so you will also need to install the Oracle Java Developer Kit using the instructions provided in Appendix B.

According to the most current documentation for the bada components of PhoneGap, the current version provides support for only the Acceleration, Camera, Compass, Device, Geolocation and Network APIs.

Downloading and Installing the Correct PhoneGap bada Files

For PhoneGap versions up to and including version 1.4.1, the default PhoneGap download available at www.phonegap.com/download-thankyou doesn’t include the project files needed to build PhoneGap applications on the bada platform. I’ve spoken with the developer responsible for PhoneGap’s bada support, and he has indicated that he will try to get the files updated in a subsequent release of the framework.

To verify whether your existing PhoneGap framework installation (installed using the instructions provided in Appendix A) contains the necessary project files, open Windows Explorer, and navigate to the folder where the PhoneGap files have been extracted. Then navigate to the bada folder and look for the .badaprj and .cproject files shown in Figure 4-1. If the files are there, you have what you need and can skip the remainder of this section.

Figure 4-1 PhoneGap bada project files

If you don’t see these two files, you will need to download a separate package from the Apache Cordova Git repository. Open your browser of choice and navigate to https://git-wip-us.apache.org/repos/asf?p=incubator-cordova-bada.git; Figure 4-2 shows the contents of the page. This is the location for the project within the Apache Incubator; the location will likely change once the project makes it out of the Apache Incubator, or, who knows, maybe they’ll change the project name yet again.

Figure 4-2 PhoneGap bada Git repository

On the page, click the “snapshot” link at the top of the list of commits, as highlighted in the figure. This will start a download of the latest version of the PhoneGap bada project files. Save the file in an appropriate location, and then extract the files. The files are currently saved in tar.gz format, so you may have to do some additional work to extract the files since Windows may not automatically recognize the format; the files extract easily using WinZip (www.winzip.com).

One last step has to be completed. The bada project download includes each of the JavaScript files that make up the standard phonegap.js file, but the actual phonegap.js file is missing. Using Windows Explorer, navigate to the resphonegap folder shown in Figure 4-3. Double-click the phonegap.bat file highlighted in the figure, and a batch process will run that will concatenate each of the JavaScript files into the phonegap.js file your PhoneGap applications will utilize.

Figure 4-3 PhoneGap bada project folder

As you can see, for bada, the PhoneGap project team has broken the naming convention for the phonegap.js file. For most other platforms, the file name includes the PhoneGap version number; for bada, it does not.

Creating a bada PhoneGap Project

Once the PhoneGap and bada SDKs have been installed, your development environment is ready to create new PhoneGap projects. As you’ll see with some other platforms, to create a new PhoneGap project for bada, instead of creating a new project in the IDE, you will instead copy an existing project and modify its contents to suit your needs.

Start the bada IDE using shortcuts installed in the Windows Start menu. When the program first launches, it will display a start page similar to the one shown in Figure 4-4. Click the Workbench icon highlighted in the figure.

Figure 4-4 bada IDE start page

As is normal with Eclipse-based IDEs, the program will prompt you to select the default location for the developer workspace used to store project files. You can either accept the default value or specify a different location as appropriate for your needs.

Once the workspace loads, open the File menu, and then select Import; the IDE will open the Import wizard shown in Figure 4-5. Expand the bada section as shown in the figure, select bada Application Project, and then click the Next button.

Figure 4-5 bada IDE Import wizard’s Select dialog

The bada IDE will then display the Import Projects dialog shown in Figure 4-6. Select the “Select root directory” option as shown in the figure, and then click the Browse button to the right of the input field. The standard Windows folder selection dialog will appear; navigate to the folder where you extracted the bada project files, and click the Done button to continue. When you complete this step correctly, the Import Projects dialog will list a PhoneGap project called Cordova under the list of projects, as shown in Figure 4-6.

Figure 4-6 bada IDE: Import Projects dialog

Select the “Copy projects into workspace” checkbox, and then click the Finish button to continue. The IDE will copy the project files to the workspace and display a screen similar to the one shown in Figure 4-7.

Figure 4-7 bada IDE

For PhoneGap projects, the index.html and associated files (such as CSS and JavaScript files plus any images and other content files) are stored in or beneath the Res folder. Expand the Res folder in the Project Explorer, and click the index.html file to open it in the editor, as shown in Figure 4-7. At this point, you can make whatever changes you want to the application’s source files and begin testing your application.

The default project in the download includes settings related to the configuration of the IDE of the developer who created the project. Before you run the application, you will have to clean up the project files. In the bada IDE, open the Project menu and select Clean; the IDE will display a dialog similar to the one shown in Figure 4-8. Click the OK button, and the IDE will process the project folder and delete any files left over from a previous build of the project.

Figure 4-8 bada IDE Clean dialog

bada projects also require a manifest file; the starting project has one included with it, but you won’t be able to use that manifest for your application. The process for creating a profile and its associated manifest file plus updating the project with your new manifest file is described in the following section.

Creating a bada Application Profile

bada uses an application profile to define settings for applications that are sold through their proprietary application storefront, the Samsung Apps Store. An application profile’s settings are defined in a manifest file (manifest.xml), which must be included in the root folder of any bada application project and added to the project’s properties. You can create internal use or test applications using a default manifest file created by the IDE, or you can create a separate profile for each application either within the IDE or from the bada developer web site.

For most mobile platforms, this part of the process is completed right before you submit to the appropriate application store, but with bada development, it can be part of the initial application project setup as well. For PhoneGap development, you create a new bada project by importing an existing one, so you’ll need to have your own profile available to add to the new project later.

To create an application profile, log into the bada developer web site using the credentials created at the beginning of the chapter. From the landing page, select the My Applications menu (highlighted in Figure 4-9), and then select Application Manager.

Figure 4-9 Samsung bada developer web site

On the page that opens, select the Create a new Application ID button, as shown on the right side of Figure 4-10.

Figure 4-10 bada Application Manager

In the first step in the process, you must define a unique name for your application. The site will open a pop-up window that prompts you for the application name (as shown in Figure 4-11) and then validates the name’s uniqueness against all other bada applications before allowing you to continue the process. Only after you have registered a unique name can you continue to provide a description of the application and then move to the next step. Click the OK button to continue.

Figure 4-11 bada Application Manager: checking bada application name availability

On the next page that appears, enter a description of the application, as shown in Figure 4-12, and then click the Create button to continue.

Figure 4-12 bada Application Manager: adding an application description

At this point, the application profile has been created, and the site will display the confirmation page shown in Figure 4-13. Before you continue, you must define at least one application version for the application. Click the Add a New Application Version link highlighted in Figure 4-13.

Figure 4-13 bada Application Manager: profile confirmation

On the next page that appears, enter a version number for the application, and then click the Save button, as shown in Figure 4-14. Notice how Samsung limits the major and minor version numbers to 35.

Figure 4-14 bada Application Manager: setting the application version

Next you will need to define the bada platform version you will be developing for. On the confirmation page shown in Figure 4-15, click the Select the bada API Version link highlighted in the figure.

Figure 4-15 bada Application Manager: application version profile created

On the page that appears, the Application Manager will prompt you to select the version of the bada SDK the application will use (API version) plus the type of application that is being created, as shown in Figure 4-16. Select the appropriate options for the application, and then click the Save button. The form should default to SDK version 2.0, but since you’re working with an older version of the SDK for PhoneGap development, you will want to change the selection to match the SDK version you’re using.

Figure 4-16 bada Application Manager: selecting API version and application type

At this point in the process, the Application Manager will display a page similar to the one shown in Figure 4-17. What you need to do next is configure application-specific security settings for the application. Click the Select your Privileged API Group link highlighted in Figure 4-17.

Figure 4-17 bada Application Manager: API version profile created

From the page that appears (shown in Figure 4-18), you can enable or disable as needed specific API permissions for the application profile. In this example, I’ve cropped the page to show only a few of the available options; when doing this for your own application profiles, you will see a much larger list of options. In Figure 4-18, the settings for access to the camera and image capture capabilities are expanded and enabled for this particular application as are settings related to working with web content. If the PhoneGap application you’re building doesn’t use either of those device features, you can disable access to those features within the application by deselecting the checkboxes shown. If you don’t set these options correctly, any portion of your application that uses an API that is not enabled here will not work.

Figure 4-18 bada Application Manager: enabling API capabilities

You can also upload an existing manifest file to capture API settings already defined for a different application. To do this, click the Choose File button on the top of the page, and select the manifest file you want to use.

Click the Save button to complete the API profile. The Application Manager will display a page similar to the one shown in Figure 4-19. Next you need to select the device feature set for the application. To do this, click the Select your Device Feature Set link highlighted in Figure 4-19.

Figure 4-19 bada Application Manager: API capabilities created

The site will display a page similar to the one shown in Figure 4-20. Since there was only one device type supported with the bada 1.2 SDK, all you will need to do here is click the Save button shown on the bottom of the figure to continue.

Figure 4-20 bada Application Manager: selecting target devices

Next you will see the page shown in Figure 4-21. From this page, click the Download manifest.xml button highlighted in the figure to download the application’s manifest file to the local system. You will need this when you build your application in the bada IDE.

Figure 4-21 bada Application Manager: completed profile

At any time, you can go back and update the settings for your application or create a profile for the next version of the application. When you return to the Application Manager, the list of defined profiles will display. Simply click the application’s name to modify the settings or add a new application version.

Once you have a manifest file, you can add it to your PhoneGap project by right-clicking the project in the IDE’s Project Explorer and selecting Properties. In the dialog that appears, expand the bada Build option, and then select Manifest Information, as shown in Figure 4-22.

Figure 4-22 bada project properties manifest settings

Click the Import button at the bottom of the dialog, and then select the manifest file you just created. After you’ve selected the file, click the OK button to save the updated project properties. At this point, the application is ready to run with your application manifest instead of the one included with the PhoneGap project.

Testing bada PhoneGap Applications

To launch an application in the bada emulator, right-click a project, open the Run As menu, and then select bada Emulator Web Application. The IDE will launch the bada device emulator and then load and execute the selected bada application. Figure 4-23 shows the HelloWorld3 application from Chapter 2 loaded in the emulator. The application source code had to be modified to accommodate the location of the phonegap.js file within the bada project’s folder structure.

Figure 4-23 bada device emulator