PhoneGap has quickly become a popular platform for building mobile applications, mainly because of the simplicity involved in creating cross-platform applications using only HTML, CSS and JavaScript. The idea is simple – you build your application in HTML5, and then add that code to your PhoneGap application, and it compiles to Android, IOS and Windows for you. PhoneGap even gives you plugins that allow you to access your device Camera, Compass, Contacts, GPS and much more. This means that you can access functionality formerly only available to the native device language using JavaScript.
In this article we are going to look at how to install PhoneGap, using the command-line interface, on Windows and MAC OS X. One caveat here is if you want to build IOS applications, you have to have your PhoneGap installation on a Mac running OS X and Xcode. For Windows Mobile, you must build your PhoneGap application in a Windows environment. Android (built in Java, essentially) can be built anywhere. Most developers I know either have a Mac with Windows installed as a Bootcamp or a Mac running Windows in a virtual machine like VMware or VirtualBox. Creating all three platforms is then as simple as copying the HTML from OS X to Windows, or vice versa.
We will be dealing with the latest stable build of PhoneGap at the moment, which is 3.1.0. I used Windows 8.0 and OS X Mavericks for this tutorial.
Install Node on Windows
To setup PhoneGap on Windows, we need to install node.js on our machine. If you do not have Node yet, head over to http://nodejs.org/ and hit the install button. This will download the Node installer. Run the installer and follow this process:
Click ‘Next’ to get started
Accept the license terms and click ‘Next’
Change the install location if you want to, and click ‘Next’
Select which features you would like installed. Default is ‘all’, which is good.
Click ‘install’ to start running the installer
Wait for the installer to complete
Success!
Install Node on OS X
To setup PhoneGap on OS X, we again need to install node.js on our machine. If you do not have Node yet, head over to http://nodejs.org/ and hit the install button. This will download the Node installer.
Double click on package you have downloaded, and follow this process:
Click ‘Continue’ to get started
Read the license terms (if you must) and click ‘Continue’
To agree to the license terms, click ‘Agree’
Choose which hard drive to install node on. Usually the default is your current drive Click ‘Install’.
Once the installer is done, click close.
To check if node is installed, you need to open your terminal. Click on the spotlight icon on the top right of your status bar (it’s a magnifying glass) and type ‘terminal’ in the search box that appears. Select ‘Terminal’ listed next to ‘Applications’.
When the terminal has opened, type: ‘node -v’. You should get a version number without any errors popping up (mine shows version v0.10.22). If you have errors, head on back to the Node website and check out the support documentation. If you have no errors showing up at this point, you’re done!
Install PhoneGap
Next, we need to install the PhoneGap command-line utility. We do this using Node, on the Windows Command Line or Mac Terminal that we previously opened.
In Windows 7, click on start, and type “cmd” in the search box. This will open your terminal window.
- In Windows 8, click the “windows” button on your keyboard and type “cmd”.
- In OS X use spotlight (as detailed above) if your terminal is not still open.
The Commands for Windows and OS X PhoneGap Installation are Identical
Inside the command line terminal, type:
$ npm install -g PhoneGap‘npm’ Is the Node Package Manager, and is the reason we needed to install Node.
If you get permission errors on OS X, you may need to run the command as the root user, as follows:
$ sudo npm install -g PhoneGapThis will ask you to confirm your password before installing PhoneGap.
Create the PhoneGap App
Now that PhoneGap is installed on your system, you can create the PhoneGap app.
Using the command-line utility, navigate to the directory that you want your application to reside in (if you want to test your application in a standard browser, this will need to be on a webserver like XAMP). Once in the directory of your choice, you need to run the command to tell PhoneGap to create the application. The syntax looks like this:
$ PhoneGap create myProject com.example.myProject MyProjectPhoneGap create– tells PhoneGap to create a new project and expect more arguments.
- myProject– is the name of the directory that the application will be created in.
- com.example.myProject– the reverse-domain style identifier for your project. If you are unsure what to use, use this example.
- MyProject – the display name of your application when it is deployed to the device.
File Structure
Once the project is created, you will notice the following directories in your project root:
- merges – Contains shared code between the platforms. This is maintained by PhoneGap and you should never touch it.
- platforms – PhoneGap builds your IOS, Android, Windows and other platforms native code here. Don’t touch.
- plugins – PhoneGap installs your plugins here. These are PhoneGap specific plugins and should not be touched.
- www – This is where you do your work. Contains js, css, img and a few other directories specific to PhoneGap. The usage here is out of the scope of this tutorial, but in general, everything starts with the index.html file in this directory.
Build the App
Next, we need to enter the application directory.
$ cd myProject
If we are running OS X and have Xcode installed, we can build an iOS application at this point. Simply run the following in your terminal:
$ PhoneGap build iosAnd the response you will see in your terminal is:
[PhoneGap] detecting iOS SDK environment...[PhoneGap] using the local environment [PhoneGap] compiling iOS...[PhoneGap] successfully compiled iOS appWhen this is done, you will notice an ‘ios’ directory in the platforms directory of your application. This directory contains your iOS-specific code that Xcode requires to build your application.’
Similarly, to build an Android application alongside the IOS application, run:
$ PhoneGap build androidThis will build an ‘android’ directory in the ‘platforms’ directory.
Android applications can be built on Windows as well as OS X.
On your Windows machine, you can build a Windows Mobile application by running:
$ PhoneGap build WindowsIt is important to note that you will only ever work in your ‘www’ directory. When PhoneGap compiles your application, it takes all of your code you have created or edited, and adds it to your IOS, Android, or Windows platforms, so you write once, run everywhere (at least for mobile).
Installing Features
The whole point of using PhoneGap, rather than just a mobile web view, is that PhoneGap gives you access to the mobile device hardware like the camera, GPS, etc. In order to use these features, we need to install PhoneGap plugins. These are done on the command line, and again, OS X and Windows commands are identical.
Device API
This allows you to obtain device information, like platform, IMEI, and more.
$ cordova plugin add org.apache.cordova.deviceNetwork Connection and Battery
$ cordova plugin add org.apache.cordova.network-information$ cordova plugin add org.apache.cordova.battery-statusAccelerometer, Compass, and Geolocation
$ cordova plugin add org.apache.cordova.device-motion$ cordova plugin add org.apache.cordova.device-orientation$ cordova plugin add org.apache.cordova.geolocationCamera, Media Playback and Capture
$ cordova plugin add org.apache.cordova.camera$ cordova plugin add org.apache.cordova.media-capture$ cordova plugin add org.apache.cordova.mediaAccess Files on Device or Network (File API)
$ cordova plugin add org.apache.cordova.file$ cordova plugin add org.apache.cordova.file-transferNotification via Dialog box or Vibration
$ cordova plugin add org.apache.cordova.dialogs$ cordova plugin add org.apache.cordova.vibrationContacts
$ cordova plugin add org.apache.cordova.contactsGlobalization
$ cordova plugin add org.apache.cordova.globalizationSplashscreen
$ cordova plugin add org.apache.cordova.splashscreenOpen New Browser Windows (InAppBrowser)
$ cordova plugin add org.apache.cordova.inappbrowserDebug Console
$ cordova plugin add org.apache.cordova.consoleDeploy to Device
To deploy to your device, you need to do the following:
Android
Make sure your device is in developer mode, and has USB debugging turned on. Connect your device to your machine and, in the command-line, type:
$ PhoneGap run androidIf your Android SDK is correctly installed on your machine, you will see, after a few minutes, that your application will open on your device.
If you want to test your application on an emulator, do the same as above, but with no device connected to your computer.
iOS
This is a little more complicated. Firstly, you need an Apple Developer account if you want to deploy to your device for testing (you can test the device on the Xcode emulator without a certificate, but Apple will not accept your application into the App Store without it being tested on at least one real device). Once this is done and you have setup a provisioning certificate for your device (see http://developer.apple.com/), you need to compile your IOS application. In your Terminal, type:
$ PhoneGap build iosYour response in the Terminal should be:
[PhoneGap] detecting iOS SDK environment...[PhoneGap] using the local environment[PhoneGap] compiling iOS...[PhoneGap] successfully compiled iOS appNow that your IOS application is compiled, you need to launch Xcode. Use Spotlight as before, and once Xcode is open, select ‘File’, then ‘Open…’ and from the file browser, navigate to your PhoneGap project. Open the ‘platforms/ios’ directory, and search for the file called ‘{yourprojectname}.xcodeproj’ and double click on it. This will open your project in Xcode.
Look at the top left of your Xcode window. You should see a ‘Play’ button (arrow pointing right), and a ‘Stop’ button (a square), and next to that, the name of your application. Next to that will be the name of an emulator – mine says iPhone Retina (4-Inch 64 Bit). If you have your iPhone, iPod or iPad plugged in, you can click on that and select your device. Then press the play button. This will build your project again in Xcode, and try to deploy it to your device. If your device is not plugged in, it will deploy it to the emulator you have selected, as seen below:
Note that every time you edit your PhoneGap project, you need to run the ‘PhoneGap build’ command before trying to run the application in Xcode. The reason is that the ‘PhoneGap build’ command copies your code from your ‘www’ directory to the ‘platform/ios/’ directory, and only then can Xcode see that your project has changed, and apply the changes.
Conclusion
Now that you have your PhoneGap application running, it’s time to start with the fun stuff – building something. Remember, you are only limited by your imagination and your knowledge of HTML, CSS and JavaScript. For more information on how to use PhoneGap, you can read the official documentation here.
