Quickly start an app using Yeoman, Ionic, AngularJS and PhoneGap

PhoneGap Ionic AngularJs

What

Here is a simple guide to get started on a new mobile project using the following technologies:

  • Ionic Framework: The beautiful, open source front-end framework for developing hybrid mobile apps with HTML5 (slides available here).
  • AngularJS: Open-source JavaScript framework.
  • PhoneGap: Open source framework that allows you to create mobile apps using standardized web APIs.
  • Yeoman: Used to booststrap the project using Grunt to handle the development process and Bower to handle the dependencies.

How

The following commands create a project Demo with package id com.example.app (tested on Mac, two scripts will be added in the git repository to automatically create your project):

  1. Install NodeJS if not installed
  2. Install development environment on your computer (XCode, Android SDK or Windows Phone SDK). Mac users could install Android SDK via Homebrew (brew install android-sdk android-ndk)
  3. npm install -g phonegap yo generator-angular ionic bower grunt (or npm -g update if already installed)
  4. mkdir demo (type this command in your sources directory or git clone an empty repository)
  5. cd demo
Yeoman (Bower and Grunt)
  1. yo angular
    • Answer Y to Would you like to use Sass (with Compass)?
    • Answer n to Would you like to include Twitter Bootstrap?
    • Select modules you want to use to Which modules would you like to include?
  2. Edit Gruntfile.js and change line dist: 'dist' with dist: 'www' (the generated directory should be www for PhoneGap)
  3. echo 'www/' >> .gitignore (Add directory www to .gitignore)
  4. echo 'npm-debug.log' >> .gitignore (Add file npm-debug.log to .gitignore)
  5. echo '.*' >> .gitignore (Add hidden files to .gitignore but you should force add bower and co configuration files to git)
  6. grunt (to check all is fine so far and to avoid phonegap to complain because the www folder has been deleted)
PhoneGap
  1. phonegap create tmp "com.example.app" "Demo"
  2. mv tmp/.cordova/ tmp/hooks/ tmp/platforms/ tmp/plugins/ tmp/www/ .
  3. mv www/config.xml app/ (Move file www/config.xml to app/)
  4. rm -rf www/ (Remove www directory because it will be generated by Grunt)
  5. Add 'config.xml' to the copy:dist:files:src section in grunt.initConfig in Gruntfile.js to copy the config.xml file into the generated directory (around line 338)
  6. Edit app/config.xml and change the preference fullscreen from true to false to prevent your app to display fullscreen.
  7. Edit app/config.xml and change the preference webviewbounce from true to false to remove default webview bouncing effect in the application.
  8. Edit app/config.xml and add the following preferences to block the webview boucing and rubber-band effect again
    • <preference name="DisallowOverscroll" value="true"/>
    • <preference name="UIWebViewBounce" value="false" />
  9. echo 'platforms/' >> .gitignore (Add directory platforms to .gitignore)
  10. echo 'plugins/' >> .gitignore (Add directory plugins to .gitignore)
  11. echo '(function () {})();' > app/phonegap.js (creates an empty phonegap.js file that will be be replaced by phonegap in app)
  12. Add'phonegap.js' to the copy:dist:files:src section in grunt.initConfig in Gruntfile.js to copy the config.xml file into the generated directory (around line 338)
  13. Add <script src="phonegap.js"></script> to app/index.html after Google Analytics snippet
  14. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git (if needed, read the doc)
  15. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git (if needed, read the doc)
  16. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git (if needed, read the doc)
  17. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git (if needed, read the doc)
  18. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git (if needed, read the doc)
  19. phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git (if needed, read the doc)
Ionic Framework
  1. Add ionic (version 1.0.0-beta.12) to bower.json below angular
  2. Run bower update to update bower installation.
  3. cat /dev/null > app/views/main.html (Remove app/view/main.html content)
  4. Load module 'ionic' in app/scripts/app.js (below 'ngRoute')
  5. Copy automatically missing fonts from ionic to grunt generated www folder. Add the following section to Gruntfile.js in section copy:dist:files in grunt.initConfig
 {
     expand: true,
     cwd: '<%= yeoman.app %>/bower_components/ionic/release',
     dest: '<%= yeoman.dist %>',
     src: ['fonts/*']
 }
Optional
  1. Remove es5-shim and json3 references in bower.json if mobile app only, those packages were needed for older browser support.
  2. Remove old browser support in index.html if mobile app only
  3. Remove Google Analytics code in app/index.html if mobile app only
  4. Use bower list to see the outdated packages
  5. npm-check-updates -u to update packages versions in package.json (add npm-check-updates version 1.2.0 in devDependencies section to package.json first and run npm install). Use this at your own risk.

Tests

  1. Update karma.conf.js and check that it contains the following lines:
 'app/bower_components/angular/angular.js',
 'app/bower_components/angular-mocks/angular-mocks.js',
 'app/bower_components/angular-resource/angular-resource.js',
 'app/bower_components/angular-cookies/angular-cookies.js',
 'app/bower_components/angular-animate/angular-animate.js',
 'app/bower_components/angular-route/angular-route.js',
 'app/bower_components/angular-ui-router/release/angular-ui-router.js',
 'app/bower_components/ionic/release/js/ionic.js',
 'app/bower_components/ionic/release/js/ionic-angular.js',
  1. Run grunt to check the whole process is fine.
  2. Don’t forget to add tests and to use Protractor.

What do you get

  1. Check installed plugins with phonegap local plugin list
  2. To serve the web files run grunt serve or run grunt serve:dist
  3. Use grunt to generate production files (code checking, minification, tests, …)
  4. Use Phonegap CLI to generate apps (always rungrunt before to get latest changes)
  5. Replace existing code with real ionic code (see github repository below)

Don’t forget to add and write tests (karma, protractor, …)

Check out the Github repository with additional code : https://github.com/MNCC/yeoman-ionic-angular-phonegap-seed

Further readings

Feel free to contact us at MNCC or via @mnccfr if you have any question.

Previous

5 Things You Should Stop Doing With jQuery

Pros & Cons Of Using Hybrid Mobile App Development In Your Business

Next