Cordova / PhoneGap

With Apache Cordova/Adobe PhoneGap, you can bundle your Famo.us application to run natively on mobile devices. In this guide, we’ll show you how to build your Famo.us project with PhoneGap and how to test it locally on your own mobile device.

The steps we’ll be covering here are:

Installing Cordova
Creating a Cordova project
Adding Famo.us files to the Cordova project
Adding device platforms
Building the project
Emulating the device platform
Viewing the Famo.us app on your device

Prerequisites

This guide assumes you’re already familiar with using a command-line interface. For simplicity, we’ll also assume you’re developing on Mac OS X. (If you’re developing in a Windows environment, the principles should be the same.) You’ll need to have installed Node.js before continuing.

Install

To use PhoneGap, we’ll first need to install Cordova, a command-line utility that will allow us to build our project.

$ npm install -g cordova

That command is all you should need to get started!

(Here’s a bit of history: PhoneGap is simply one distribution of Apache Cordova. Think of Cordova as the engine, with PhoneGap being a project built upon that engine. For most purposes, you can think of them as one and the same.)

Create the PhoneGap app

Now we need to set up a new PhoneGap application. First, cd to the folder where you put all of your projects, then run the following command:

$ cordova create hello-famous

That command will create a folder called hello-famous inside the current directory. The generated hello-famous folder contains special metadata about the project that Cordova will use when wrapping our app.

cd into the hello-famous folder before continuing. We’ll be running all of the following commands from within that folder.

Create a Famo.us app

Let’s create a fresh Famo.us project.

First, download the Famo.us Starter Kit ↓. Unzip the download. In the unzipped Starter Kit folder, you should find an index.html file, a src folder, and a css folder. If you open the index.html file in your browser, you should see the familiar spinning Famo.us logo.

We need to copy our files from this project into the www directory inside the hello-famous PhoneGap project. First, remove all the files from the www directory, then copy the Famo.us files in. PhoneGap will use these files when building the project.

Add platforms

We need to decide what platforms we want to deploy our Famo.us application to. PhoneGap supports a variety of platforms, and it’s up to you to choose which to target. For simplicity, in this lesson we’ll just target the iOS platform.

Add the iOS platform to the Cordova project by running the following command (again, within the hello-famous folder):

$ cordova platform add ios

This command will install the platform-specific packages needed to wrap your application to run on iOS devices.

Build the app

With a skeletal Cordova project set up, we’re ready to build our (admittedly simple) project for the platforms we’ve targeted. To build the app, run this command:

$ cordova build

As Cordova builds your project, you’ll see a lot of text fly by your console. When the build process succeeds, you should see a “BUILD SUCCEEDED” message in your Terminal window.

Now, it’s time to test out our new native application.

Test the app in an emulator

PhoneGap offers several tools for emulating different mobile platforms on your development workstation. But first, we need to install them. We can install the iOS platform simulator like so:

$ npm install -g ios-sim

With the iOS simulator installed, we can run the emulator from the hello-famous folder:

$ cordova emulate ios

This command will run several generator tasks, then launch a new window that contains the emulation environment. After a few moments, you should see the spinning Famo.us logo appear in the emulator window. Congratulations! You’ve just built your app to run natively!

Serve to a real device

To do an initial test of our wrapped app on a real device, we’re going to install a special app on our iOS device that can run the application as served from our development workstation. Follow these steps:

Connect your iOS device to the local WiFi network – the same network your workstation is connected to.
Find your workstation’s IP address. (Look under System Preferences > Network and select the connected WiFi network. An IP address should be listed. The IP address should begin with 192.168.)
Serve the Famo.us + PhoneGap project. From the hello-world directory on your development workstation, run $ cordova serve.
On your iOS device, download and install the free PhoneGap Developer application. Once installed, open it.
In the PhoneGap Developer app interface on your iOS device, enter the IP address above in the “Server Address” field, followed by the port number (it should be 8000). The full address should be something like 192.168.123.456:8000. Tap the ‘Connect’ button and wait. After a moment, you should see a ‘SUCCESS!’ message. The application should begin running.
You will initially see a “Package Metadata” page with a list of packages. Click the “ios” link to see the application fully launched.

Deploy

To deploy a packaged app to your iOS device and app stores, you’ll need to follow several additional steps that are out of scope for this beginners-oriented lesson. You can refer to the PhoneGap Documentation on deployment for information about the steps required.

More info

There’s plenty of additional information about PhoneGap and Cordova around the web: