AngularJS, Phonegap, and Angular Seed. Let's Go!

I have been wanting to learn how to write a mobile app with Phonegap for, well...since I first heard there was such an incredible thing as Phonegap. The very idea that it could make a Objective-C ignorant (but js ambitious) developer like myself, able to take his satisfactory JS/HTML/CSS code and transform it into a satisfactory mobile experience. Yay, Phonegap. But, you probably aren't here because you don't know what Phonegap is, you're probably here because you want to put the oh-so-interesting angularjs framework onto a phone and do incredible things. Well, so did I. I found great tutorials, the best of which is definitely this 4-part delight by @markcoleman.

Phonegap and Angularjs the Start

I would've been lost without it. However, after I completed it I wanted to build my own app, and I was looking for a place to start. In my exploratory phase with angular, I had discovered the angular-seed project and angular-phonecat tutorial. I knew angular-seed would start me out with runnable jasmine unit tests, an end-to-end suite, a web-server, and some other niceties. That's when I got the bright idea that I should just make angular-seed run as a phonegap app! 8 hours later...

If you follow this guide I think you can have angular-seed running in the XCode simulator in less than 30 minutes. Exciting right? I know.

Install Phonegap CLI and angular-seed

I assume you're not an idiot and you already have NodeJS. If not; my god, go get it! From your command line install the Phonegap CLI and create a new phonegap project, I'll be calling it "seedgap", but you need to call it whatever the hell you want.

ANYWHERE I USE "seedgap" FROM HERE ON: YOU NEED TO USE "whateverthehellyouwant".

If you want to make it easy on yourself. Copy and paste this tutorial to your editor and utilize search and replace. Now, let's pull down the seed so we can gap it. If ya know what I'm talkin bout.

npm install -g phonegap
cd path/where/you/do/work/
phonegap create seedgap com.example.seedgap SeedGap
git clone https://github.com/angular/angular-seed.git

Mate the two projects

I'm asking you to trust me. Just run these commands and everything will be okay. The first two commands here are pretty tricky and I'll explain them. But the others are very basic movement stuff.

cd angular-seed/
find . -type f -not -path '*.git*' -exec sed -i '' 's/app\//www\//g' {} +

That find and sed is looking through the angular-seed project and replacing "app/" with "www/". Basically, phonegap uses the www/ folder to compile, and we want to put our stuff in there, and that means for angular-seed's tests and scripts to work we have change the code anywhere it references that path.

Remove unnecessary phonegap files.

cd ../
rm seedgap/www/spec.html
rm -R seedgap/www/spec/
rm seedgap/www/img/logo.png
rm seedgap/www/css/index.css
touch seedgap/www/img/.gitkeep

Move the angular-seed goodness to seedgap.

cp angular-seed/app/js/* seedgap/www/js/
cp angular-seed/app/css/* seedgap/www/css/
cp -R angular-seed/app/lib/ seedgap/www/lib
cp -R angular-seed/app/partials/ seedgap/www/partials
mv seedgap/www/index.html seedgap/www/index-old.html
cp angular-seed/app/index.html seedgap/www/index.html
cp angular-seed/{package.json,README.md} seedgap/
cp -R angular-seed/config/ seedgap/config
cp -R angular-seed/logs/ seedgap/logs
cp -R angular-seed/scripts/ seedgap/scripts
cp -R angular-seed/test/ seedgap/test

Edit a little bit of code

Here again, trust me. Everything you see me do here, I learned...no...stole from someone who actually knew what they were doing.

Copy lines 23-24 from seedgap/www/index-old.html and paste them to line 5 of seedgap/www/index.html. The <head> in index.html should look like this:

<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>My AngularJS App</title>
  <link rel="stylesheet" href="css/app.css"/>
</head>

Copy lines 36-37 in seedgap/www/index-old.html and paste them to line 23 of seedgap/www/index.html.

Copy lines 38-40 of seedgap/www/index-old.html and paste them to line 31 of seedgap/www/index.html.

Your javascript dependencies should look like this:

  <!-- In production use:
  <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular.min.js"></script>
  -->
  <script type="text/javascript" src="phonegap.js"></script>
  <script type="text/javascript" src="js/index.js"></script>
  <script src="lib/angular/angular.js"></script>
  <script src="js/app.js"></script>
  <script src="js/services.js"></script>
  <script src="js/controllers.js"></script>
  <script src="js/filters.js"></script>
  <script src="js/directives.js"></script>
  <script type="text/javascript">
    app.initialize();
  </script>

Alright, we're done with index-old.html.

rm seedgap/www/index-old.html

Edit seedgap/www/js/index.js, change the recievedEvent method to look like this:

#!javascript
receivedEvent: function(id) {
  console.log('Received Event: ' + id);
  angular.bootstrap(document, ["myApp"]);
}

Run your angular tests

This is the moment.

cd seedgap/
npm install .
./scripts/test.sh

The above should output your unit tests, and setup a watch task to run tests whenever you save a file.

To run the e2e tests open up two terminal windows. Get back to the seedgap directory and in one window start a node server.

node ./scripts/web-server.js

In the other run your e2e test suite.

./scripts/e2e-test.sh

Compile your App for iPhone

Phonegap is so easy. Go back to your seedgap directory.

phonegap build ios

It has now compiled a project to seedgap/platforms/ios/SeedGap.xcodeproj. In finder, navigate to it and open it up in XCode.

Hit the play button in the upper left of Xcode to run the app in the simulator.

Ripple emulator

If you still have your web-server.js file running from a few steps back. Just download ripple and then navigate to http://localhost:8000/www/index.html. Run the ripple chrome extension and follow its instructions to see your app run in a variety of emulator environments.

Cheers!

Thank you for reading, I hope this is a helpful guide. I'm planning to simplify the nasty bits by starting a github repo that makes it easier. If you found this interesting, please help me by passing it along. I am nackjicholson on github, and @nackjicholsonn with two n's on twitter. If you have questions, suggestions, fixes, or insults, there is a convenient comment box below.

nackjicholson/angular-phonegap-seed.md