From 76b853bcbc28343206bcd3b1c8de65243f5572c7 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 15:43:55 -0500 Subject: [PATCH 01/22] Create FAQ.md --- docs/FAQ.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/FAQ.md diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..e41a276 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,12 @@ +#Frequently asked questions + +##How do I manage libraries with Bower? +Install a new front-end library using `bower install --save` to update your `bower.json` file. + +``` + +bower install --save lodash + +``` + +This way, when the Grunt [`bower-install`](https://github.com/stephenplusplus/grunt-bower-install#grunt-bower-install) task is run it will automatically inject your front-end dependencies inside the `bower:js` block of your `app/index.html`file. From 4415cec5dc2e380c05fff15d705a2ed7a77b5615 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 15:48:49 -0500 Subject: [PATCH 02/22] Update FAQ.md --- docs/FAQ.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index e41a276..bcd4dfc 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -10,3 +10,6 @@ bower install --save lodash ``` This way, when the Grunt [`bower-install`](https://github.com/stephenplusplus/grunt-bower-install#grunt-bower-install) task is run it will automatically inject your front-end dependencies inside the `bower:js` block of your `app/index.html`file. + +##Can I manually add libraries? +Of course! If a library you wish to include is not registered with Bower or you wish to manually manage third party libraries, simply include any CSS and JavaScript files you need **inside** your `app/index.html` [usemin](https://github.com/yeoman/grunt-usemin#blocks) `build:js` or `build:css` blocks but **outside** the `bower:js` or `bower:css` blocks (since the Grunt task overwrites the Bower blocks' contents). From 3718fc843e1378f3dbf6e263e63f59b9150ecdac Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 15:55:05 -0500 Subject: [PATCH 03/22] Create getting-started.md --- docs/getting-started.md | 42 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/getting-started.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..a2016cc --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,42 @@ +#Getting Started + +## Initial Walkthrough + +To help you hit the ground running, let's walk through an example workflow together. We're assuming you've followed the +[usage](https://github.com/diegonetto/generator-ionic#usage) directions and are inside your app's directory. + + + +We'll start by running our app in a browser so we can make a few changes. + +``` + +grunt serve + +``` + +Play around with livereload by changing some of the styles in `app/styles/main.css` or HTML in one of the files in `app/templates/`. When you're ready, lets go ahead and build the assets for Cordova to consume and also spot check that we didn't bork any code during the build process. We can do that with another handy Grunt task that runs the build process and then launches a `connect` server for use to preview the app with our built assets. + +``` + +grunt serve:dist + +``` + +If everything looks good the next step is to add a platform target and then emulate our app. In order for us to launch the iOS simulator from the command line, we'll have to install the `ios-sim` package. (If you forget to do this, Cordova will kindly remind you). + +``` + +npm install -g ios-sim + +grunt platform:add:ios + +grunt emulate:ios + +``` + +You may have realized that when the Grunt build process is run, it triggers the Cordova build system as well, so you end up with a beautifully packaged mobile app in a single command. + + + +consolelogs - on serve and emulate From ee9d6f0ed1930e86fb3ea6e78d8bf79ff6d77ae0 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:03:49 -0500 Subject: [PATCH 04/22] Create app-testing --- docs/app-testing | 49 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/app-testing diff --git a/docs/app-testing b/docs/app-testing new file mode 100644 index 0000000..70a6851 --- /dev/null +++ b/docs/app-testing @@ -0,0 +1,49 @@ +## Testing Your App + +To lessen the pain of testing your application, this generator configures your project with a handful of libraries that will hopefully make testing your application, dare I say, more enjoyable. + + + +![Comic](http://dilbert.com/dyn/str_strip/000000000/00000000/0000000/100000/10000/6000/600/116640/116640.strip.gif) + + + +### Unit Tests + +The foundation of our testing solution is built using [Karma](http://karma-runner.github.io/) which was created by the AngularJS team and is all around awesome. Inside of your generated `karma.conf.js` file you will find some basic configuration settings. Notice that we're using [Mocha](http://visionmedia.github.io/mocha/) to structure our tests and pulling in [Chai](http://chaijs.com/), a slick assertion library. You can easily drop Chai and replace Mocha with [Jasmine](http://jasmine.github.io/) depending on your preference. + + + +Your generated `Gruntfile.js` also contains a `karma` task that provides further configuration. Any properties specified via this task will override the values inside `karma.conf.js` when run via `grunt`. If you look closely at this task, you'll notice that we're using [PhantomJS](http://phantomjs.org/) for both Karma targets, but you can easily update the `karma:unit` target to run tests inside of real browsers. + + + +Ok, now that you have some context (and links to read up on the bundled testing libraries), go ahead and run `grunt test` and open up one of the included unit tests - `test/spec/controllers.js`. In your editor of choice, change this line - `scope.pets.should.have.length(4);` to any number other than four and watch what happens. Since your test files are being watched for changes, Grunt knows to go ahead and re-run your test suite, which in this cause should have errored out with a failure message being displayed in your terminal. + + + +Undo your modification and ensure that all tests are passing before continuing on. + + + +**Note** Depending on which starter template you picked, your tests may start off failing. + + + +### End2End Tests + +Coming soon! + + + +### Code Coverage + +So you've finished writing your tests, why not showoff just how watertight your application has become? Using [Istanbul](http://gotwarlost.github.io/istanbul/) - which was built at Yahoo - we can generate visually engaging code coverage reports that do just that! + + + +Our beloved generator has done all the hard work for you, so go ahead and see these coverage reports in action by running `grunt coverage`. + + + +If this is your first time using Istanbul, take a look around. It will help you spot gaps in your unit tests and lets face it, the more visual gratification we can get during our testing stage, the greater the likelihood of us sitting down and writing these tests to begin with! From f5c08dff454d5012d6e913c72832d29636a2e42a Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:04:59 -0500 Subject: [PATCH 05/22] Delete app-testing --- docs/app-testing | 49 ------------------------------------------------ 1 file changed, 49 deletions(-) delete mode 100644 docs/app-testing diff --git a/docs/app-testing b/docs/app-testing deleted file mode 100644 index 70a6851..0000000 --- a/docs/app-testing +++ /dev/null @@ -1,49 +0,0 @@ -## Testing Your App - -To lessen the pain of testing your application, this generator configures your project with a handful of libraries that will hopefully make testing your application, dare I say, more enjoyable. - - - -![Comic](http://dilbert.com/dyn/str_strip/000000000/00000000/0000000/100000/10000/6000/600/116640/116640.strip.gif) - - - -### Unit Tests - -The foundation of our testing solution is built using [Karma](http://karma-runner.github.io/) which was created by the AngularJS team and is all around awesome. Inside of your generated `karma.conf.js` file you will find some basic configuration settings. Notice that we're using [Mocha](http://visionmedia.github.io/mocha/) to structure our tests and pulling in [Chai](http://chaijs.com/), a slick assertion library. You can easily drop Chai and replace Mocha with [Jasmine](http://jasmine.github.io/) depending on your preference. - - - -Your generated `Gruntfile.js` also contains a `karma` task that provides further configuration. Any properties specified via this task will override the values inside `karma.conf.js` when run via `grunt`. If you look closely at this task, you'll notice that we're using [PhantomJS](http://phantomjs.org/) for both Karma targets, but you can easily update the `karma:unit` target to run tests inside of real browsers. - - - -Ok, now that you have some context (and links to read up on the bundled testing libraries), go ahead and run `grunt test` and open up one of the included unit tests - `test/spec/controllers.js`. In your editor of choice, change this line - `scope.pets.should.have.length(4);` to any number other than four and watch what happens. Since your test files are being watched for changes, Grunt knows to go ahead and re-run your test suite, which in this cause should have errored out with a failure message being displayed in your terminal. - - - -Undo your modification and ensure that all tests are passing before continuing on. - - - -**Note** Depending on which starter template you picked, your tests may start off failing. - - - -### End2End Tests - -Coming soon! - - - -### Code Coverage - -So you've finished writing your tests, why not showoff just how watertight your application has become? Using [Istanbul](http://gotwarlost.github.io/istanbul/) - which was built at Yahoo - we can generate visually engaging code coverage reports that do just that! - - - -Our beloved generator has done all the hard work for you, so go ahead and see these coverage reports in action by running `grunt coverage`. - - - -If this is your first time using Istanbul, take a look around. It will help you spot gaps in your unit tests and lets face it, the more visual gratification we can get during our testing stage, the greater the likelihood of us sitting down and writing these tests to begin with! From afed0d301e768d6b1f1edcd2373543aa7eb7d64d Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:05:19 -0500 Subject: [PATCH 06/22] Create app-testing.md --- docs/app-testing.md | 49 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/app-testing.md diff --git a/docs/app-testing.md b/docs/app-testing.md new file mode 100644 index 0000000..70a6851 --- /dev/null +++ b/docs/app-testing.md @@ -0,0 +1,49 @@ +## Testing Your App + +To lessen the pain of testing your application, this generator configures your project with a handful of libraries that will hopefully make testing your application, dare I say, more enjoyable. + + + +![Comic](http://dilbert.com/dyn/str_strip/000000000/00000000/0000000/100000/10000/6000/600/116640/116640.strip.gif) + + + +### Unit Tests + +The foundation of our testing solution is built using [Karma](http://karma-runner.github.io/) which was created by the AngularJS team and is all around awesome. Inside of your generated `karma.conf.js` file you will find some basic configuration settings. Notice that we're using [Mocha](http://visionmedia.github.io/mocha/) to structure our tests and pulling in [Chai](http://chaijs.com/), a slick assertion library. You can easily drop Chai and replace Mocha with [Jasmine](http://jasmine.github.io/) depending on your preference. + + + +Your generated `Gruntfile.js` also contains a `karma` task that provides further configuration. Any properties specified via this task will override the values inside `karma.conf.js` when run via `grunt`. If you look closely at this task, you'll notice that we're using [PhantomJS](http://phantomjs.org/) for both Karma targets, but you can easily update the `karma:unit` target to run tests inside of real browsers. + + + +Ok, now that you have some context (and links to read up on the bundled testing libraries), go ahead and run `grunt test` and open up one of the included unit tests - `test/spec/controllers.js`. In your editor of choice, change this line - `scope.pets.should.have.length(4);` to any number other than four and watch what happens. Since your test files are being watched for changes, Grunt knows to go ahead and re-run your test suite, which in this cause should have errored out with a failure message being displayed in your terminal. + + + +Undo your modification and ensure that all tests are passing before continuing on. + + + +**Note** Depending on which starter template you picked, your tests may start off failing. + + + +### End2End Tests + +Coming soon! + + + +### Code Coverage + +So you've finished writing your tests, why not showoff just how watertight your application has become? Using [Istanbul](http://gotwarlost.github.io/istanbul/) - which was built at Yahoo - we can generate visually engaging code coverage reports that do just that! + + + +Our beloved generator has done all the hard work for you, so go ahead and see these coverage reports in action by running `grunt coverage`. + + + +If this is your first time using Istanbul, take a look around. It will help you spot gaps in your unit tests and lets face it, the more visual gratification we can get during our testing stage, the greater the likelihood of us sitting down and writing these tests to begin with! From 80f255162edf579585aaa97608205f5e868f5085 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:10:11 -0500 Subject: [PATCH 07/22] Update getting-started.md --- docs/getting-started.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index a2016cc..e33a082 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,5 @@ #Getting Started -## Initial Walkthrough - To help you hit the ground running, let's walk through an example workflow together. We're assuming you've followed the [usage](https://github.com/diegonetto/generator-ionic#usage) directions and are inside your app's directory. From c2b3437955671a81271aeb1ac4a6bb22754dcb62 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:19:01 -0500 Subject: [PATCH 08/22] Create android.md --- docs/android.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/android.md diff --git a/docs/android.md b/docs/android.md new file mode 100644 index 0000000..89e1bf7 --- /dev/null +++ b/docs/android.md @@ -0,0 +1,127 @@ +## Android Walkthrough + +Research & Contribution by @ltfschoen (Luke Schoen) + + + +- Install Generator Ionic + +``` + +npm cache clear + +npm install -g generator-ionic + +mkdir my-ionic-project && cd $_ + +yo ionic + +``` + +- Execute the following command in Terminal program to run a web server on your localhost. This will automatically open a tab in your default web browser at the following address and load your app http://127.0.0.1:9000/ + +``` + +grunt serve + +``` + +- Now we want to emulate your app on an Android Virtual Device (AVD). Start by downloading the latest [Android SDK](https://developer.android.com/sdk/index.html#download) + +- On a Mac OS, extract downloaded ZIP file to an installation directory (i.e. /Applications/adt-bundle-mac-x86_64-20140702/). Note that the folder should match the name of the downloaded ZIP file adt-bundle-mac-x86_64-20140702.zip + +- Update the Bash Profile document to include PATH environment variables to the Android SDK platform-tools and tools directory so the 'android' command may be executed regardless of your present working directory in the Terminal program. Note: This step may be necessary in order to allow you to use the 'android' command and avoid encountering the following error: + +``` + +[Error: The command android failed. Make sure you have the latest Android SDK installed, and the android command (inside the tools/ folder) added to your path. Output: /bin/sh: android: command not found ] + +``` + +- Execute the following command in the Terminal program to edit your Bash Profile document: + +``` + +touch ~/.bash_profile; open ~/.bash_profile + +``` + +- Copy and Paste the following at the top of the file (without removing existing data within the file). Replace all instances of adt-bundle-mac-x86_64-20140702 that are shown below with the filename of the ZIP file that you downloaded. Save and close the file. + +``` + +export PATH=/user/local/bin:$PATH + +export PATH=$PATH:/Applications/adt-bundle-mac-x86_64-20140702/sdk/tools + +export PATH=${PATH}:/Applications/adt-bundle-mac-x86_64-20140702/sdk/tools:/Applications/adt-bundle-mac-x86_64-20140702/sdk/tools + +``` + +- Execute the updated Bash Profile with the following command in the Terminal program to update the PATH: + +``` + +source ~/.bash_profile + +``` + +- Execute the following command in Terminal program to install Apache Ant using Homebrew + +``` + +brew install ant + +``` + +- Note: The above step may be necessary to avoid encountering the following error: + +``` + +Error: ERROR : executing command 'ant', make sure you have ant installed and added to your path. + +``` + +- Execute the following command in Terminal program to open the Android Package Manager (APM): + +``` + +android + +``` + +- In the APM, expand Android 4.4.2 (API 19). Click checkboxes to install "SDK Platform" and "ARM EABI v7A System Image". Click "Install Packages..." + +- Go to the Android SDK Manager menu in the top left of your screen. Click the "Tools" dropdown menu. Click "Manage AVDs...". This opens the AVD (Android Virtual Device) Manager. Click to select the device listed (i.e. default is AVD_for_Nexus Android 4.4.2). Click the "Repair..." Button on the right panel. Click the "Refresh" Button at the bottom right. Close the window. + +- Execute the following command in Terminal program to install the Android Debug Bridge: + +``` + +brew install android-platform-tools + +``` + +- Note: The above steps may be necessary to avoid encountering the following errors: + +``` + +Error: Please install Android target 19 (the Android newest SDK). Make sure you have the latest Android tools installed as well. Run "android" from your command-line to install/update any missing SDKs or tools. + +Error executing "adb devices": /bin/sh: adb: command not found + +emulator: ERROR: This AVD's configuration is missing a kernel file!! + +``` + +- Add the Android Platform with the following commands in Terminal program. No warnings or errors should be encountered. Note that it may take a while to load your app in the Android emulator. + +``` + +grunt platform:add:android + +grunt build + +grunt emulate:android + +``` From ed02467d8198f8916fc77a2fe7cc36ccba1d8a08 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:20:27 -0500 Subject: [PATCH 09/22] Update getting-started.md --- docs/getting-started.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index e33a082..daee9d4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -38,3 +38,11 @@ You may have realized that when the Grunt build process is run, it triggers the consolelogs - on serve and emulate + +#Android Walkthrough + +Check out this [doc](https://github.com/DanielSilv/generator-ionic/blob/master/docs/android.md) if you would like a detailed android walkthrough! + +#Testing + +Now that you've started, why not learn how to [test](https://github.com/DanielSilv/generator-ionic/blob/master/docs/app-testing.md) your app? From fadedc4cfbeed2ce2c15f102782e5791f26b88a7 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:22:38 -0500 Subject: [PATCH 10/22] Update FAQ.md --- docs/FAQ.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index bcd4dfc..0c8d642 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -13,3 +13,30 @@ This way, when the Grunt [`bower-install`](https://github.com/stephenplusplus/gr ##Can I manually add libraries? Of course! If a library you wish to include is not registered with Bower or you wish to manually manage third party libraries, simply include any CSS and JavaScript files you need **inside** your `app/index.html` [usemin](https://github.com/yeoman/grunt-usemin#blocks) `build:js` or `build:css` blocks but **outside** the `bower:js` or `bower:css` blocks (since the Grunt task overwrites the Bower blocks' contents). + +##How do I use the Ripple Emulator? +**Be Advised**: [Ripple](http://ripple.incubator.apache.org/) is under active development so expect support for some plugins to be missing or broken. + + + +Add a platform target then run `grunt ripple` to launch the emulator in your browser. + +``` + +grunt platform:add:ios + +grunt ripple + +``` + + + +Now go edit a file and then refresh your browser to see your changes. (Currently experimenting with livereload for Ripple) + + + +**Note**: If you get errors beginning with `Error: static() root path required`, don't fret. Ripple defaults the UI to Android so just switch to an iOS device and you'll be good to go. + + + +![Ripple](http://i.imgur.com/LA4Hip1l.png) From 6a31d1965a855ed7a42b588ed7f274b66916d440 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:27:17 -0500 Subject: [PATCH 11/22] Update README.md --- docs/README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 191 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 1d31b8a..0cb9dd8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,193 @@ # Ionic Generator documentation -FAQ and Guides coming soon. +## Workflow + +The included Grunt build system provides sensible defaults to help optimize and automate several aspects of your workflow when developing hybrid-mobile apps using the Ionic Framework. + + +### Local browser development + +Running `grunt serve` enhances your workflow by allowing you to rapidly build Ionic apps without having to constantly re-run your platform simulator. Since we spin up a `connect` server with `watch` and `livereload` tasks, you can freely edit your CSS (or SCSS/SASS files if you chose to use Compass), HTML, and JavaScript files and changes will be quickly reflected in your browser. + + + +### Building assets for Cordova + +Once you're ready to test your application in a simulator or device, run `grunt cordova` to copy all of your `app/` assets into `www/` and build updated `platform/` files so they are ready to be emulated / run by Cordova. + + + +To compress and optimize your application, run `grunt build`. It will concatenate, obfuscate, and minify your JavaScript, HTML, and CSS files and copy over the resulting assets into the `www/` directory so the compressed version can be used with Cordova. + + + +### Cordova commands + +To make our lives a bit simpler, the `cordova` library has been packaged as a part of this generator and delegated via Grunt tasks. To invoke Cordova, simply run the command you would normally have, but replace `cordova` with `grunt` and `spaces` with `:` (the way Grunt chains task arguments). + + + +For example, lets say you want to add iOS as a platform target for your Ionic app + +``` + +grunt platform:add:ios + +``` + +and emulate a platform target + +``` + +grunt emulate:ios + +``` + +or add a plugin by specifying either its full repository URL or namespace from the [Plugins Registry](http://plugins.cordova.io) + +``` + +grunt plugin:add:https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git + +grunt plugin:add:org.apache.cordova.device + +grunt plugin:add:org.apache.cordova.network-information + +``` + +## Icons and Splash Screens + +Properly configuring your app icons and splash screens to work with Cordova can be a pain to set up, so we've gone ahead and including an `after_prepare` hook that manages copying these resource files to the correct location within your current platform targets. + + + +To get started, you must first add a platform via `grunt platform:add:ios`. Once you have a platform, the packaged `icons_and_splashscreens.js` hook will copy over all placeholder icons and splash screens generated by Cordova into a newly created top-level `resources/` directory inside of your project. Simply replace these files with your own resources (**but maintain file names and directory structure**) and let the hook's magic automatically manage copying them to the appropriate location for each Cordova platform, all without interrupting your existing workflow. + + + +To learn more about hooks, checkout out the `README.md` file inside of your `hooks/` directory. + + + +## Environment Specific Configuration + +While building your Ionic app, you may find yourself working with multiple environments such as development, staging, and production. This generator uses [grunt-ng-constant] (https://github.com/werk85/grunt-ng-constant) to set up your workflow with development and production environment configurations right out of the box. + + + +### Adding Constants + +To set up your environment specific constants, modify the respective targets of the `ngconstant` task located towards the top of your Gruntfile. + +``` + + ngconstant: { + + options: { + + space: ' ', + + wrap: '"use strict";\n\n {%= __ngModule %}', + + name: 'config', + + dest: '<%= yeoman.app %>/scripts/config.js' + + }, + + development: { + + constants: { + + ENV: { + + name: 'development', + + apiEndpoint: 'http://dev.your-site.com:10000/' + + } + + } + + }, + + production: { + + constants: { + + ENV: { + + name: 'production', + + apiEndpoint: 'http://api.your-site.com/' + + } + + } + + } + + }, + +``` + + + +Running `grunt serve` will cause the `development` target constants to be used. When you build your application for production using `grunt build` or `grunt serve:dist`, the `production` constants will be used. Other targets, such as staging, can be added, but you will need to customize your Gruntfile accordingly. Note that if you change the `name` property of the task options, you will need to update your `app.js` module dependencies as well. + + + +### Using Inside Angular + +A `config.js` file is created by `grunt-ng-constant` depending on which task target is executed. This config file exposes a `config` module, that is listed as a dependency inside `app/scripts/app.js`. Out of the box, your constants will be namespaced under `ENV`, but this can be changed by modifying the `ngconstant` targets. It is important to note that whatever namespace value is chosen is what will need to be used for Dependency Injection inside your Angular functions. + + + +The following example shows how to pre-process all outgoing HTTP request URLs with an environment specific API endpoint by creating a simple Angular `$http` interceptor. + + + +``` + +// Custom Interceptor for replacing outgoing URLs + +.factory('httpEnvInterceptor', function (ENV) { + + return { + + 'request': function(config) { + + if (!_.contains(config.url, 'html')) { + + config.url = ENV.apiEndpoint + config.url; + + } + + return config; + + } + + } + +}) + + + +.config(function($httpProvider) { + + // Pre-process outgoing request URLs + + $httpProvider.interceptors.push('httpEnvInterceptor'); + +}) + +``` + + +## Special Thanks To + +* The pioneers behind [Yeoman](http://yeoman.io/) for building an intelligent workflow management solution. + +* The [AngularJS Generator](https://github.com/yeoman/generator-angular) and [Ionic Seed Project](https://github.com/driftyco/ionic-angular-cordova-seed) projects for inspiration. + +* The visionaries at [Drifty](http://drifty.com) for creating the [Ionic Framework](http://ionicframework.com/). From 7bacc54510335d6362ac26668e3593bbc2482124 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:30:45 -0500 Subject: [PATCH 12/22] Update getting-started.md --- docs/getting-started.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index daee9d4..7e23cee 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,9 @@ #Getting Started +## Workflow +The included Grunt build system provides sensible defaults to help optimize and automate several aspects of your workflow when developing hybrid-mobile apps using the Ionic Framework. + +##Walkthrough To help you hit the ground running, let's walk through an example workflow together. We're assuming you've followed the [usage](https://github.com/diegonetto/generator-ionic#usage) directions and are inside your app's directory. From 700dd923b1ae1d7ccd8a4935c9c5a22e531aa062 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:32:50 -0500 Subject: [PATCH 13/22] Update FAQ.md --- docs/FAQ.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index 0c8d642..d441bf1 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -40,3 +40,10 @@ Now go edit a file and then refresh your browser to see your changes. (Currently ![Ripple](http://i.imgur.com/LA4Hip1l.png) + +##How do I build assets for Cordova? +Once you're ready to test your application in a simulator or device, run `grunt cordova` to copy all of your `app/` assets into `www/` and build updated `platform/` files so they are ready to be emulated / run by Cordova. + + + +To compress and optimize your application, run `grunt build`. It will concatenate, obfuscate, and minify your JavaScript, HTML, and CSS files and copy over the resulting assets into the `www/` directory so the compressed version can be used with Cordova. From 081861846194966b0ad250eefde5beaace89aa97 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:47:33 -0500 Subject: [PATCH 14/22] Update README.md --- docs/README.md | 133 ------------------------------------------------- 1 file changed, 133 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0cb9dd8..1bb30e7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,142 +1,9 @@ # Ionic Generator documentation -## Workflow - -The included Grunt build system provides sensible defaults to help optimize and automate several aspects of your workflow when developing hybrid-mobile apps using the Ionic Framework. - - -### Local browser development - -Running `grunt serve` enhances your workflow by allowing you to rapidly build Ionic apps without having to constantly re-run your platform simulator. Since we spin up a `connect` server with `watch` and `livereload` tasks, you can freely edit your CSS (or SCSS/SASS files if you chose to use Compass), HTML, and JavaScript files and changes will be quickly reflected in your browser. - - - -### Building assets for Cordova - -Once you're ready to test your application in a simulator or device, run `grunt cordova` to copy all of your `app/` assets into `www/` and build updated `platform/` files so they are ready to be emulated / run by Cordova. - - - -To compress and optimize your application, run `grunt build`. It will concatenate, obfuscate, and minify your JavaScript, HTML, and CSS files and copy over the resulting assets into the `www/` directory so the compressed version can be used with Cordova. - - - -### Cordova commands - -To make our lives a bit simpler, the `cordova` library has been packaged as a part of this generator and delegated via Grunt tasks. To invoke Cordova, simply run the command you would normally have, but replace `cordova` with `grunt` and `spaces` with `:` (the way Grunt chains task arguments). - - - -For example, lets say you want to add iOS as a platform target for your Ionic app - -``` - -grunt platform:add:ios - -``` - -and emulate a platform target - -``` - -grunt emulate:ios - -``` - -or add a plugin by specifying either its full repository URL or namespace from the [Plugins Registry](http://plugins.cordova.io) - -``` - -grunt plugin:add:https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git - -grunt plugin:add:org.apache.cordova.device - -grunt plugin:add:org.apache.cordova.network-information - -``` - -## Icons and Splash Screens - -Properly configuring your app icons and splash screens to work with Cordova can be a pain to set up, so we've gone ahead and including an `after_prepare` hook that manages copying these resource files to the correct location within your current platform targets. - - - -To get started, you must first add a platform via `grunt platform:add:ios`. Once you have a platform, the packaged `icons_and_splashscreens.js` hook will copy over all placeholder icons and splash screens generated by Cordova into a newly created top-level `resources/` directory inside of your project. Simply replace these files with your own resources (**but maintain file names and directory structure**) and let the hook's magic automatically manage copying them to the appropriate location for each Cordova platform, all without interrupting your existing workflow. - - - -To learn more about hooks, checkout out the `README.md` file inside of your `hooks/` directory. - - - ## Environment Specific Configuration While building your Ionic app, you may find yourself working with multiple environments such as development, staging, and production. This generator uses [grunt-ng-constant] (https://github.com/werk85/grunt-ng-constant) to set up your workflow with development and production environment configurations right out of the box. - - -### Adding Constants - -To set up your environment specific constants, modify the respective targets of the `ngconstant` task located towards the top of your Gruntfile. - -``` - - ngconstant: { - - options: { - - space: ' ', - - wrap: '"use strict";\n\n {%= __ngModule %}', - - name: 'config', - - dest: '<%= yeoman.app %>/scripts/config.js' - - }, - - development: { - - constants: { - - ENV: { - - name: 'development', - - apiEndpoint: 'http://dev.your-site.com:10000/' - - } - - } - - }, - - production: { - - constants: { - - ENV: { - - name: 'production', - - apiEndpoint: 'http://api.your-site.com/' - - } - - } - - } - - }, - -``` - - - -Running `grunt serve` will cause the `development` target constants to be used. When you build your application for production using `grunt build` or `grunt serve:dist`, the `production` constants will be used. Other targets, such as staging, can be added, but you will need to customize your Gruntfile accordingly. Note that if you change the `name` property of the task options, you will need to update your `app.js` module dependencies as well. - - - ### Using Inside Angular A `config.js` file is created by `grunt-ng-constant` depending on which task target is executed. This config file exposes a `config` module, that is listed as a dependency inside `app/scripts/app.js`. Out of the box, your constants will be namespaced under `ENV`, but this can be changed by modifying the `ngconstant` targets. It is important to note that whatever namespace value is chosen is what will need to be used for Dependency Injection inside your Angular functions. From 4188740cc70375b02239acb58ae1f17c053a28a0 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:48:33 -0500 Subject: [PATCH 15/22] Update README.md --- docs/README.md | 47 ----------------------------------------------- 1 file changed, 47 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1bb30e7..d3a89da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,53 +4,6 @@ While building your Ionic app, you may find yourself working with multiple environments such as development, staging, and production. This generator uses [grunt-ng-constant] (https://github.com/werk85/grunt-ng-constant) to set up your workflow with development and production environment configurations right out of the box. -### Using Inside Angular - -A `config.js` file is created by `grunt-ng-constant` depending on which task target is executed. This config file exposes a `config` module, that is listed as a dependency inside `app/scripts/app.js`. Out of the box, your constants will be namespaced under `ENV`, but this can be changed by modifying the `ngconstant` targets. It is important to note that whatever namespace value is chosen is what will need to be used for Dependency Injection inside your Angular functions. - - - -The following example shows how to pre-process all outgoing HTTP request URLs with an environment specific API endpoint by creating a simple Angular `$http` interceptor. - - - -``` - -// Custom Interceptor for replacing outgoing URLs - -.factory('httpEnvInterceptor', function (ENV) { - - return { - - 'request': function(config) { - - if (!_.contains(config.url, 'html')) { - - config.url = ENV.apiEndpoint + config.url; - - } - - return config; - - } - - } - -}) - - - -.config(function($httpProvider) { - - // Pre-process outgoing request URLs - - $httpProvider.interceptors.push('httpEnvInterceptor'); - -}) - -``` - - ## Special Thanks To * The pioneers behind [Yeoman](http://yeoman.io/) for building an intelligent workflow management solution. From dd81052c3a856da449c43c5b54238169584c47d6 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 16:56:59 -0500 Subject: [PATCH 16/22] Update FAQ.md --- docs/FAQ.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index d441bf1..08930fa 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -41,9 +41,163 @@ Now go edit a file and then refresh your browser to see your changes. (Currently ![Ripple](http://i.imgur.com/LA4Hip1l.png) +##Why is Cordova included and how do I use it? +To make our lives a bit simpler, the `cordova` library has been packaged as a part of this generator and delegated via Grunt tasks. To invoke Cordova, simply run the command you would normally have, but replace `cordova` with `grunt` and `spaces` with `:` (the way Grunt chains task arguments). + + + +For example, lets say you want to add iOS as a platform target for your Ionic app + +``` + +grunt platform:add:ios + +``` + +and emulate a platform target + +``` + +grunt emulate:ios + +``` + +or add a plugin by specifying either its full repository URL or namespace from the [Plugins Registry](http://plugins.cordova.io) + +``` + +grunt plugin:add:https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git + +grunt plugin:add:org.apache.cordova.device + +grunt plugin:add:org.apache.cordova.network-information + +``` + ##How do I build assets for Cordova? Once you're ready to test your application in a simulator or device, run `grunt cordova` to copy all of your `app/` assets into `www/` and build updated `platform/` files so they are ready to be emulated / run by Cordova. To compress and optimize your application, run `grunt build`. It will concatenate, obfuscate, and minify your JavaScript, HTML, and CSS files and copy over the resulting assets into the `www/` directory so the compressed version can be used with Cordova. + +##How do I configure my icons and splash screens? +Properly configuring your app icons and splash screens to work with Cordova can be a pain to set up, so we've gone ahead and including an `after_prepare` hook that manages copying these resource files to the correct location within your current platform targets. + + + +To get started, you must first add a platform via `grunt platform:add:ios`. Once you have a platform, the packaged `icons_and_splashscreens.js` hook will copy over all placeholder icons and splash screens generated by Cordova into a newly created top-level `resources/` directory inside of your project. Simply replace these files with your own resources (**but maintain file names and directory structure**) and let the hook's magic automatically manage copying them to the appropriate location for each Cordova platform, all without interrupting your existing workflow. + + + +To learn more about hooks, checkout out the `README.md` file inside of your `hooks/` directory. + +##What are the benefits of local browser development? +Running `grunt serve` enhances your workflow by allowing you to rapidly build Ionic apps without having to constantly re-run your platform simulator. Since we spin up a `connect` server with `watch` and `livereload` tasks, you can freely edit your CSS (or SCSS/SASS files if you chose to use Compass), HTML, and JavaScript files and changes will be quickly reflected in your browser. + +##How do I add constants? +To set up your environment specific constants, modify the respective targets of the `ngconstant` task located towards the top of your Gruntfile. + +``` + + ngconstant: { + + options: { + + space: ' ', + + wrap: '"use strict";\n\n {%= __ngModule %}', + + name: 'config', + + dest: '<%= yeoman.app %>/scripts/config.js' + + }, + + development: { + + constants: { + + ENV: { + + name: 'development', + + apiEndpoint: 'http://dev.your-site.com:10000/' + + } + + } + + }, + + production: { + + constants: { + + ENV: { + + name: 'production', + + apiEndpoint: 'http://api.your-site.com/' + + } + + } + + } + + }, + +``` + + + +Running `grunt serve` will cause the `development` target constants to be used. When you build your application for production using `grunt build` or `grunt serve:dist`, the `production` constants will be used. Other targets, such as staging, can be added, but you will need to customize your Gruntfile accordingly. Note that if you change the `name` property of the task options, you will need to update your `app.js` module dependencies as well. + +##How is this used inside Angular? +A `config.js` file is created by `grunt-ng-constant` depending on which task target is executed. This config file exposes a `config` module, that is listed as a dependency inside `app/scripts/app.js`. Out of the box, your constants will be namespaced under `ENV`, but this can be changed by modifying the `ngconstant` targets. It is important to note that whatever namespace value is chosen is what will need to be used for Dependency Injection inside your Angular functions. + + + +The following example shows how to pre-process all outgoing HTTP request URLs with an environment specific API endpoint by creating a simple Angular `$http` interceptor. + + + +``` + +// Custom Interceptor for replacing outgoing URLs + +.factory('httpEnvInterceptor', function (ENV) { + + return { + + 'request': function(config) { + + if (!_.contains(config.url, 'html')) { + + config.url = ENV.apiEndpoint + config.url; + + } + + return config; + + } + + } + +}) + + + +.config(function($httpProvider) { + + // Pre-process outgoing request URLs + + $httpProvider.interceptors.push('httpEnvInterceptor'); + +}) + +``` + +##What else does this generator do to help me? +While building your Ionic app, you may find yourself working with multiple environments such as development, staging, and production. This generator uses [grunt-ng-constant] (https://github.com/werk85/grunt-ng-constant) to set up your workflow with development and production environment configurations right out of the box. From c3cf13d5722928b20aa288cbf05b4cec3a3b2db2 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Thu, 16 Oct 2014 17:05:05 -0500 Subject: [PATCH 17/22] Update README.md --- docs/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index d3a89da..ff8d433 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,9 @@ # Ionic Generator documentation -## Environment Specific Configuration - -While building your Ionic app, you may find yourself working with multiple environments such as development, staging, and production. This generator uses [grunt-ng-constant] (https://github.com/werk85/grunt-ng-constant) to set up your workflow with development and production environment configurations right out of the box. +* [Getting Started](https://github.com/DanielSilv/generator-ionic/blob/master/docs/getting-started.md) - Learn the basics +* [Android Development](https://github.com/DanielSilv/generator-ionic/blob/master/docs/android.md) - In-depth Android Walkthrough +* [FAQ](https://github.com/DanielSilv/generator-ionic/blob/master/docs/FAQ.md) - Answers to your common questions +* [App Testing](https://github.com/DanielSilv/generator-ionic/blob/master/docs/app-testing.md) - Learn how to test the app ## Special Thanks To From 6499f487dee91044c89e504a7a5deb7b56c65606 Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Fri, 17 Oct 2014 11:00:53 -0500 Subject: [PATCH 18/22] Update getting-started.md --- docs/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 7e23cee..53af2fa 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -45,8 +45,8 @@ consolelogs - on serve and emulate #Android Walkthrough -Check out this [doc](https://github.com/DanielSilv/generator-ionic/blob/master/docs/android.md) if you would like a detailed android walkthrough! +Check out this [doc](android.md) if you would like a detailed android walkthrough! #Testing -Now that you've started, why not learn how to [test](https://github.com/DanielSilv/generator-ionic/blob/master/docs/app-testing.md) your app? +Now that you've started, why not learn how to [test](app-testing.md) your app? From 00d62c3a46056bf90cb73cc3c4728bf98d7b082e Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Fri, 17 Oct 2014 11:01:41 -0500 Subject: [PATCH 19/22] Update README.md --- docs/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index ff8d433..7e8a694 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,9 @@ # Ionic Generator documentation -* [Getting Started](https://github.com/DanielSilv/generator-ionic/blob/master/docs/getting-started.md) - Learn the basics -* [Android Development](https://github.com/DanielSilv/generator-ionic/blob/master/docs/android.md) - In-depth Android Walkthrough -* [FAQ](https://github.com/DanielSilv/generator-ionic/blob/master/docs/FAQ.md) - Answers to your common questions -* [App Testing](https://github.com/DanielSilv/generator-ionic/blob/master/docs/app-testing.md) - Learn how to test the app +* [Getting Started](getting-started.md) - Learn the basics +* [Android Development](android.md) - In-depth Android Walkthrough +* [FAQ](FAQ.md) - Answers to your common questions +* [App Testing](app-testing.md) - Learn how to test the app ## Special Thanks To From 1f301bac24989710b777237763bf9c221ca5b07d Mon Sep 17 00:00:00 2001 From: Diego Netto Date: Fri, 24 Oct 2014 12:27:18 -0500 Subject: [PATCH 20/22] fix(ionic): Run ionic and watch concurrently. Closes #114, #116, & #121 --- templates/common/Gruntfile.js | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/templates/common/Gruntfile.js b/templates/common/Gruntfile.js index c5f4b39..30fb734 100644 --- a/templates/common/Gruntfile.js +++ b/templates/common/Gruntfile.js @@ -303,6 +303,12 @@ module.exports = function (grunt) { }, concurrent: { + ionic: { + tasks: [], + options: { + logConcurrentOutput: true + } + }, server: [<% if (compass) { %> 'compass:server',<% } %> 'copy:styles', @@ -478,21 +484,14 @@ module.exports = function (grunt) { // Wrap ionic-cli commands grunt.registerTask('ionic', function() { + var done = this.async(); var script = path.resolve('./node_modules/ionic/bin/', 'ionic'); var flags = process.argv.splice(3); - var child = spawn(script, this.args.concat(flags)); - child.stdout.on('data', function (data) { - grunt.log.writeln(data); - }); - child.stderr.on('data', function (data) { - grunt.log.error(data); + var child = spawn(script, this.args.concat(flags), { stdio: 'inherit' }); + child.on('close', function (code) { + code = code ? false : true; + done(code); }); - process.on('exit', function (code) { - child.kill('SIGINT'); - process.exit(code); - }); - - return grunt.task.run(['watch']); }); grunt.registerTask('test', [ @@ -502,18 +501,22 @@ module.exports = function (grunt) { 'karma:unit:start', 'watch:karma' ]); + grunt.registerTask('serve', function (target) { if (target === 'compress') { return grunt.task.run(['compress', 'ionic:serve']); } - grunt.task.run(['init', 'ionic:serve']); + grunt.config('concurrent.ionic.tasks', ['ionic:serve', 'watch']); + grunt.task.run(['init', 'concurrent:ionic']); }); grunt.registerTask('emulate', function() { - return grunt.task.run(['init', 'ionic:emulate:' + this.args.join()]); + grunt.config('concurrent.ionic.tasks', ['ionic:emulate:' + this.args.join(), 'watch']); + return grunt.task.run(['init', 'concurrent:ionic']); }); grunt.registerTask('run', function() { - return grunt.task.run(['init', 'ionic:run:' + this.args.join()]); + grunt.config('concurrent.ionic.tasks', ['ionic:run:' + this.args.join(), 'watch']); + return grunt.task.run(['init', 'concurrent:ionic']); }); grunt.registerTask('build', function() { return grunt.task.run(['init', 'ionic:build:' + this.args.join()]); From d6cf0d08bd33c232a2642976dcf2a5fd42d779d9 Mon Sep 17 00:00:00 2001 From: Diego Netto Date: Fri, 24 Oct 2014 12:28:19 -0500 Subject: [PATCH 21/22] 0.6.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 765cc9f..50f4c68 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "generator-ionic", - "version": "0.6.0", + "version": "0.6.1", "description": "A generator for the Ionic Framework", "keywords": [ "yeoman-generator", From 3516f23ae20205f06f5dd2f3072638d0fbd385c2 Mon Sep 17 00:00:00 2001 From: Diego Netto Date: Fri, 24 Oct 2014 12:29:18 -0500 Subject: [PATCH 22/22] docs(docs): Update Changelog --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53afde4..4a3f8c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ + +## 0.6.1 (2014-10-24) + + +#### Bug Fixes + +* **ionic:** Run ionic and watch concurrently., #116, & #121 ([1f301bac](http://github.com/diegonetto/generator-ionic/commit/1f301bac24989710b777237763bf9c221ca5b07d), closes [#114](http://github.com/diegonetto/generator-ionic/issues/114)) + + ## 0.6.0 (2014-10-06)