PhoneGap 3 Hello World in OS X

I have been using PhoneGap 2.x for a couple of months and it’s a good framework that can help you to deliver a cross-browser product quick without knowing all the technologies behind the devices. I wanted to update to the new version because it has support for ios7, and I like the new approach for the modular plugins.

PhoneGap 3.x make an extensive use of the PhoneGap CLI in contrast to a manual installation, in the following tutorial we’re going to make a step-by-step installation of PhoneGap 3.0.2 with a hello world application on a iOS emulator running on OS X.

Prerequisites

Install Xcode (you can install it from the AppStore)
Install PhoneGap command-line tool
1. Install Node.js (download the mac package from http://nodejs.org/download/)
2. Install PhoneGap framework: open a mac terminal and type
  sudo npm install -g phonegap

Create the App

Now that our mac have installed the framework lets create the application

In the terminal, go to the folder where you will create your project
Type the following to create your project:
phonegap create TabletPrototype com.robalarcon.tabletprototype TabletPrototype

note: in the line above we are calling the “create” method of the “phonegap” command, and we’re sending three parameters, first the name of the app directory, secondly the reverse domain-style identifier, and at last the application display text (the last two arguments are optional and you can set them later in the app config.xml file)

What phonegap does when we call the “create command”? Well it will create a sample project for us, this sample project will contain all the necessary files to run a hello world project that is attached to the “device ready” PhoneGap event, all of this in the “www” folder that is where we have our web assets that represent our application.

I’m listening “Say Hello” by the Whings, good song

Build the App

Change to the directory that we created on the last step
cd TabletPrototype
Install ios-sim app (this is to be able to invoke the ios emulator in the console without using xcode)
sudo npm install -g ios-sim
Install phonegap ios
phonegap install ios

The last step will install our app in the ios emulator (emulating an iphone retina)

O.K. more than that is happening, and knowing this is helpful if you need to open your project on Xcode for any reason (like the one bellow in this post), remember when we used the “create” function of phonegap? When we did that, we create a folder structure for our code base inside of our app main folder we have four folders:

merges
platforms
plugins
www

We already know that ‘www’ is our work space, but the other three folders are empty after the ‘create’ call, well what happen after we call “phonegap install ios” is interesting, that command did some stuff for us:

It created a folder called ios, inside of that folder there’s a lot of folders and files, for this tutorial we’re interested in two of them (the www folder and the .xcodeproj file), but all of those documents are important, they are the phonegap app, all the dependencies that the app need to run are there (ios classes to run the webview and that specifies that the app start with the ‘index..html’ archive).
It copied our “development” www folder into the ios folder, it’s an exact copy, and it is not linked with our dev www folder, so if you change something in your www dev folder, you have to run the ‘phonegap install ios again.

Changing the ios Emulator Device in Xcode

As the time of this writing I cannot find a way to change the “emulator target” device for ios, so We will do that on Xcode, to open the project in Xcode, you have to navigate to the root folder and open the “platforms” folder, find and open the “ios” folder, finally open the “.xcodeproj” file (in my case TabletPrototype.xcodeproj), once that the project has been opened, just press the play button and the emulator should start:

Important: The code that the emulator is running is the code inside the ‘www folder’ in the ios folder inside the ‘platforms’ folder. Where I am going with this? The code that you will see in Xcode source three is not your development code, is the code that is copied by the ‘phonegap install ios’ command to the ‘/platforms/ios/www’ folder. So be aware of this, try to just code in your ‘www’ development folder.

Voilà, we can start building our app.

Beginning the Real development

If you want to continue your development with the template provided by the PhoneGap Download, you can do it, the only thing you need to do is to delete the following folders and files:

“res folder”,
“spec folder”,
“icon.png file”,
“spect.html file”,

all the content inside the css folder, all the content inside img folder, and, all the content inside the js folder.

now go to your index.html file and replace all its content to the following basic hello world code:

<html>
 <head>
 <meta charset="utf-8" />
 <meta name="format-detection" content="telephone=no" />
 <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />

<title></title>
 </head>
 <body>
 <h1>PhoneGap 3.x Hello World</h1>
 <!-- load phonegap script (the phonegap "server" will generate this file in the root) -->
 <script type="text/javascript" src="phonegap.js"></script>
 <script type="text/javascript">

 var __onDeviceReady = function() {
 alert('Device is Ready: application can start.');
 };

document.addEventListener('deviceready', __onDeviceReady, false);

</script>
 </body>
</html>

this is just a header tag that you can remove, we are loading the phongegap.js library in a script tag, and we are attaching an alert to the “deviceready” event of phonegap.js, when you run this example you should see a message like this:

That’s a good point of start so you can beginning coding your PhoneGap Application.

Resources:

ios-sim: http://outof.me/phonegap-2-0-getting-started/
PhoneGap CLI guide: http://docs.phonegap.com/en/3.2.0/guide_cli_index.md.html
Deploying PhoneGap to ipad: http://stackoverflow.com/questions/18455661/how-do-you-deploy-phonegap-app-to-ipad

rob.alarcon

Articles about JavaScript, CSS, HTML and general programming.

PhoneGap 3 Hello World in OS X