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):
- Install NodeJS if not installed
- 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
) npm install -g phonegap yo generator-angular ionic bower grunt
(ornpm -g update
if already installed)mkdir demo
(type this command in your sources directory orgit clone
an empty repository)cd demo
Yeoman (Bower and Grunt)
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?
- Edit Gruntfile.js and change line
dist: 'dist'
withdist: 'www'
(the generated directory should be www for PhoneGap) echo 'www/' >> .gitignore
(Add directory www to .gitignore)echo 'npm-debug.log' >> .gitignore
(Add file npm-debug.log to .gitignore)echo '.*' >> .gitignore
(Add hidden files to .gitignore but you should force add bower and co configuration files to git)grunt
(to check all is fine so far and to avoid phonegap to complain because the www folder has been deleted)
PhoneGap
phonegap create tmp "com.example.app" "Demo"
mv tmp/.cordova/ tmp/hooks/ tmp/platforms/ tmp/plugins/ tmp/www/ .
mv www/config.xml app/
(Move file www/config.xml to app/)rm -rf www/
(Remove www directory because it will be generated by Grunt)- 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) - Edit app/config.xml and change the preference fullscreen from true to false to prevent your app to display fullscreen.
- Edit app/config.xml and change the preference webviewbounce from true to false to remove default webview bouncing effect in the application.
- 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" />
echo 'platforms/' >> .gitignore
(Add directory platforms to .gitignore)echo 'plugins/' >> .gitignore
(Add directory plugins to .gitignore)echo '(function () {})();' > app/phonegap.js
(creates an empty phonegap.js file that will be be replaced by phonegap in app)- 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) - Add
<script src="phonegap.js"></script>
to app/index.html after Google Analytics snippet phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
(if needed, read the doc)phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git
(if needed, read the doc)phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git
(if needed, read the doc)phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
(if needed, read the doc)phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git
(if needed, read the doc)phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git
(if needed, read the doc)
Ionic Framework
- Add
ionic
(version 1.0.0-beta.12) tobower.json
belowangular
- Run
bower update
to update bower installation. cat /dev/null > app/views/main.html
(Remove app/view/main.html content)- Load module
'ionic'
in app/scripts/app.js (below'ngRoute'
) - 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
- Remove es5-shim and json3 references in
bower.json
if mobile app only, those packages were needed for older browser support. - Remove old browser support in index.html if mobile app only
- Remove Google Analytics code in app/index.html if mobile app only
- Use
bower list
to see the outdated packages npm-check-updates -u
to update packages versions inpackage.json
(addnpm-check-updates
version1.2.0
indevDependencies
section to package.json first and runnpm install
). Use this at your own risk.
Tests
- 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',
- Run
grunt
to check the whole process is fine. - Don’t forget to add tests and to use Protractor.
What do you get
- Check installed plugins with
phonegap local plugin list
- To serve the web files run
grunt serve
or rungrunt serve:dist
- Use
grunt
to generate production files (code checking, minification, tests, …) - Use Phonegap CLI to generate apps (always run
grunt
before to get latest changes) - 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
- Sample Mobile Application with Ionic and AngularJS
- Ionic – Mobile UI Framework for PhoneGap/Cordova Developers
- PhoneGap – Icons and Splash Screens Help
- Apps With AngularJS
- AngularJS Tutorial for designers
- Nomad for iOS development
- The Faster Android Emulator
- Plugreg to browse Cordova/PhoneGap plugins
- PhoneGap Build
- EggHead Angular Video Training
- Google Javascript Style Guide
- Google HTML/CSS Style Guide
- Understanding the GitHub Workflow
- Apache Ripple
Feel free to contact us at MNCC or via @mnccfr if you have any question.