{"id":1178,"date":"2016-07-07T16:29:23","date_gmt":"2016-07-07T16:29:23","guid":{"rendered":"https:\/\/ionic.io\/blog\/?p=1178"},"modified":"2017-04-03T19:51:09","modified_gmt":"2017-04-03T19:51:09","slug":"advanced-workflows-for-building-rock-solid-ionic-apps-part-3","status":"publish","type":"post","link":"https:\/\/ionic.io\/blog\/advanced-workflows-for-building-rock-solid-ionic-apps-part-3","title":{"rendered":"Advanced Workflows for Building Rock-Solid Ionic Apps, Part 3"},"content":{"rendered":"

Jonathan Grupp<\/a> is a software engineer at M-Way Solutions<\/a>, the owner and maintainer of Generator-M-Ionic, and a frequent contributor to Ionic. He has written a three-part series on advanced workflows for building rock-solid Ionic apps. This is Part 3.<\/em><\/p>\n

\"blog-03\"

The air is getting a little thin in app-development orbit! Luckily, Part 3 of this series comes with a sweet oxygen mask full of life-saving elements: environments, CORS proxies, and build tools for app icons, splash screens, build variables, and app delivery. Take a deep breath and extend the project we made space-ready in Part 2<\/a>.
\n<\/p>\n

Gulp Environments<\/h3>\n

You have your app all set up, and you added plugins and other components, while implementing your app logic. At some point, you will probably want to exchange data with an external backend. No problem: Just inject the good old Angular $http service<\/a>, handle all the HTTP calls with that nice Angular promise API<\/a>, and you’re done. For instance, let’s suppose I want to shoot some requests at the Postman Echo API<\/a>.<\/p>\n

$http.get('https:\/\/echo.getpostman.com\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
Yeah! It’s as simple as that!<\/p>\n
\n  The customer changes the URL of the endpoint (that’s the beta version of the API): https:\/\/blabber.getpostman.com<\/code>.\n<\/p><\/blockquote>\n
Urgh. “OK, if that keeps happening, I’m going to put the URL in a constant,”<\/em> you might think. Clever! Luckily, your project already comes with a Config<\/code> constant in app\/main\/constants\/config-const.js<\/code>. Just adapt your code.<\/p>\n
.constant('Config', {\n  API_ENDPOINT: 'https:\/\/blabber.getpostman.com'\n  \/\/ ..\n});\n<\/code><\/pre>\n
$http.get(Config.API_ENDPOINT + '\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
\n  The customer tells you that some of the features you need to implement only work with the beta API https:\/\/blabber.getpostman.com<\/code>, and some only work with the production API https:\/\/echo.getpostman.com<\/code>.\n<\/p><\/blockquote>\n
You might worry that you’ll need to exchange the endpoint URL all the time, but worry not; Environments<\/a> to the rescue! There’s two JSON files in app\/main\/constants\/<\/code>, which you will fill with the endpoints:<\/p>\n
\/\/ env-dev.json\n{\n  "API_ENDPOINT": "https:\/\/blabber.getpostman.com"\n}\n<\/code><\/pre>\n
\/\/ env-prod.json\n{\n  "API_ENDPOINT": "https:\/\/echo.getpostman.com"\n}\n<\/code><\/pre>\n
Modify your controller code:<\/p>\n
$http.get(Config.ENV.API_ENDPOINT + '\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
Now, if you run one of these:<\/p>\n
gulp watch\n# or\ngulp build\n# or\ngulp --cordova "run <platform>"\n# or anything similar\n<\/code><\/pre>\n
Without any flags, it will default to the dev environment, and your HTTP calls will end up against the API_ENDPOINT<\/code> of your env-dev.json<\/code>:  https:\/\/blabber.getpostman.com<\/code>. How? Because the environments task injects the contents of the JSON file in the ENV<\/code> object of your Config<\/code> constant:<\/p>\n
angular.module('main')\n.constant('Config', {\n\n  \/\/ gulp environment: injects environment vars\n  ENV: {\n    \/*inject-env*\/\n    'API_ENDPOINT': 'https:\/\/blabber.getpostman.com'\n    \/*endinject*\/\n  },\n  \/\/ ..\n});\n<\/code><\/pre>\n
On the other hand, adding the --env=prod<\/code> flag like below will send your HTTP calls to https:\/\/echo.getpostman.com<\/code>, the API_ENDPOINT<\/code> of your env-prod.json<\/code>.<\/p>\n
gulp watch --env=prod\n<\/code><\/pre>\n
YEAH!<\/p>\n
What’s this sorcery? Environments come in handy for a variety of tasks: managing different API keys, tokens, logging levels, feature switches, and, as we just found out, API endpoints. And the best part: you can have as many environments as you want! A more detailed explanation of this incomprehensible, yet so appealing, piece of magic is available in our Environments Guide<\/a>.<\/p>\n
CORS & Proxying<\/h3>\n
Phew, we took care of that API-spaghetti. But wait, what’s that? Suddenly, something like this shows up in your development console as you send an HTTP request. And it is in radiant red!<\/p>\n
XMLHttpRequest cannot load https:\/\/echo.getpostman.com\/. The\n'Access-Control-Allow-Origin' header contains the invalid value ''.\nOrigin 'http:\/\/localhost:3000' is therefore not allowed access.\n<\/code><\/pre>\n
Most of us have been there: “Hello, improperly configured REST API!”<\/em>. And believe me, my team and I have been beaten by issues with CORS<\/a> (Cross-Origin Resource Sharing) MANY times, so I wrote down a little guide on how to deal with CORS issues & Proxying<\/a> in general. There are a variety of options, and depending in your project, some might work better than others.<\/p>\n
One of the most straightforward ones, which is also covered in the guide I just mentioned, is the built-in proxy<\/a> that comes with your Generator-M-Ionic project.<\/p>\n
Remember that piece of code from earlier? This will actually run into a CORS error using that API endpoint:<\/p>\n
$http.get('https:\/\/echo.getpostman.com\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
In order to configure the built-in proxy, I’ll just start gulp watch<\/code> with the following parameters:<\/p>\n
gulp watch --proxyPath=\/proxy --proxyMapTo=https:\/\/echo.getpostman.com\n<\/code><\/pre>\n
And now, the following request to my proxy will give me the response from https:\/\/echo.getpostman.com\/get<\/code> that I want.<\/p>\n
$http.get('\/proxy\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
In fact, now I can send any request of the pattern \/proxy\/**\/*<\/code>, and it’ll be mapped to https:\/\/echo.getpostman.com\/**\/*<\/code> through the proxy. This goes especially nicely with the generator’s Environments feature<\/a>, because then you can just code it like this:<\/p>\n
$http.get(Config.ENV.API_ENDPOINT + '\/get')\n.then(function (response) {\n  console.log(response);\n});\n<\/code><\/pre>\n
With the contents of your environment JSON files being:<\/p>\n
\/\/ env-dev.json\n{\n  "API_ENDPOINT": "\/proxy"\n}\n<\/code><\/pre>\n
\/\/ env-prod.json\n{\n  "API_ENDPOINT": "https:\/\/echo.getpostman.com"\n}\n<\/code><\/pre>\n
And then switch between firing against the proxy or directly at the API using the --env<\/code> flag:<\/p>\n
# will default to --env=dev and thus use the proxy\ngulp watch --proxyPath=\/proxy --proxyMapTo=https:\/\/echo.getpostman.com\n\n# the built version will fire direclty against the API\ngulp build --env=prod\n<\/code><\/pre>\n
As simple as that! No more manual, tedious, and error-prone changing of the endpoints.<\/p>\n
Quite useful, isn’t it?<\/p>\n
Default tasks<\/h3>\n
But yes, I get it, typing that whole thing also is kind of tedious:<\/p>\n
gulp watch --proxyPath=\/proxy --proxyMapTo=https:\/\/echo.getpostman.com\n<\/code><\/pre>\n
Especially if you add --env=prod<\/code> or --no-open<\/code> to the list, which I like to use to prevent the browser from opening a new window every time. Wouldn’t it be nice if my project just knew<\/em> that I want those flags to run with gulp watch<\/code>? We thought so, too! So that’s why we built this neat little task called gulp defaults<\/code>. The syntax is fairly easy:<\/p>\n
gulp defaults --set="watch --no-open --proxyPath=\/proxy --proxyMapTo=https:\/\/echo.getpostman.com"\n<\/code><\/pre>\n
Now, every time I run gulp watch<\/code>, Gulp will add those three flags for me. Woohoo! It even reminds me which flags I’ve set on every run, so I don’t get confused.<\/p>\n
\"gulp_defaults\"
Learn more about Gulp defaults and how to clear, overwrite, and share defaults across your team via Git in our Gulp defaults Guide<\/a>.<\/p>\n
Building and delivering your app<\/h3>\n
The first testable version of your app is ready. You’re proud, and the customer is eagerly waiting to test your app. The customer has the following requirements for the hand-over:
\n– deliver two apps
\n– one for each of the APIs and to not confuse the customer:
\n– a different app icon and splash screen for each version
\n– show the date and time of the build in the app<\/p>\n
Generator-M-Ionic<\/a> has tools for all of that.<\/p>\n
Building your app<\/h4>\n
Building your app with Cordova is just as easy as running your app on a device:<\/p>\n
gulp --cordova "build ios"\n<\/code><\/pre>\n
Remember that this implicitly runs gulp build<\/code> first and then triggers Cordova’s build command<\/a>, as explained in our Development Introduction<\/a>, and is the equivalent of running these two one after another:<\/p>\n
gulp build\ngulp --cordova "build ios" --no-build\n<\/code><\/pre>\n
However, for proper code-signing, it’s sometimes necessary to go with Cordova’s prepare command<\/a> and then open the platform’s project located in platforms\/<\/code> and perform the code-signing, building and all that, for instance, in Xcode<\/a> when building for iOS.<\/p>\n
gulp --cordova "prepare ios" # also runs `gulp build` first\n<\/code><\/pre>\n
Build for different APIs<\/h4>\n
Since we’ve already configured our environments<\/a> properly, building for two different APIs is just as easy as developing for two different APIs. And we already know how to do that using gulp watch<\/code> and the --env<\/code> flag. To build one app for each environment is just as easy:<\/p>\n
# build with dev environment\ngulp --cordova "build ios" --env=dev\n\n# build with prod environment\ngulp --cordova "build ios" --env=prod\n<\/code><\/pre>\n
The --env=dev<\/code> flag is not necessary, since the environment always defaults to the dev environment with every command but I like to be explicit here to make it more obvious what’s happening.<\/p>\n
Ok, done! Building different apps for each API. Next challenge!<\/p>\n
Build with different app icons and splash screens<\/h4>\n
I’m not going to go into the particulars of this one, since there’s a perfectly nice Icons and splash screens Guide<\/a> in our documentation. Whether you just have one set of icons and splash screens or ten, it’s fairly simple to set up and use. After proper configuration all you need to do in order to build with different resources is to add the --res<\/code> flag like so:<\/p>\n
# build with dev set of resources\ngulp --cordova "build ios" --res=dev\n\n# build with prod set of resources\ngulp --cordova "build ios" --res=prod\n<\/code><\/pre>\n
So, final frontier! How do we display the date and time of the build in our app?<\/p>\n
Injecting variables from the command line<\/h4>\n
At some point, especially when you’re automating the build process of your apps by continuously integrating<\/a> with Jenkins<\/a> or Travis<\/a> you might want to inject data into your app through the command line. Granted, showing the date and time of a build in the app is not a very useful use-case. In reality, you’re more likely to find yourself wanting to append build numbers into your app’s version number, which in turn is read from the config.xml<\/code> and inject both of them in the app. And guess what? There’s a guide for doing both of those things<\/a>. But for now, to keep things simple and for the lack of a better example, we’ll just stick with injecting something simple, like a date.<\/p>\n
You may have noticed that in your Config<\/code> constant is another block that looks similar to the one where the whole environment variables<\/a> get injected. That block is exactly the place where you can inject variables into your app from the command line using gulp watch<\/code> and any tasks that uses gulp build<\/code> implicitly. See how:<\/p>\n
# running $(date +%s) will only work on Unix\ngulp watch --buildVars="buildTime:$(date +%s),buildNo:12"\n<\/code><\/pre>\n
Running the above command will produce this output in the Config<\/code> const:<\/p>\n
angular.module('main')\n.constant('Config', {\n\n  \/\/ gulp environment: injects environment vars\n  ENV: {\n    \/*inject-env*\/\n    'API_ENDPOINT': 'https:\/\/blabber.getpostman.com'\n    \/*endinject*\/\n  },\n\n  \/\/ gulp build-vars: injects build vars\n  BUILD: {\n    \/*inject-build*\/\n    'buildTime': '1462972664',\n    'buildNo': '12'\n    \/*endinject*\/\n  }\n\n});\n<\/code><\/pre>\n
So you can map in one of your controllers:<\/p>\n
this.build = Config.BUILD;\n<\/code><\/pre>\n
And using the Angular date filter<\/a> in the matching template show the date and build number in your app:<\/p>\n
<ion-item class="item item-icon">\n  <!-- multiply by 1000 to convert from unix to JS timestamp -->\n  {{ctrl.build.buildTime * 1000 | date:'medium'}}\n<\/ion-item>\n<ion-item class="item item-icon">\n  {{ctrl.build.buildNo}}\n<\/ion-item>\n<\/code><\/pre>\n
Putting it all together<\/h4>\n
The only thing left to do is to merge all of what we just did for our build. Build the app with different environments, different sets of resources, and inject variables from the command line:<\/p>\n
# build dev version\ngulp build --env=dev --res=dev --buildVars="buildTime:$(date +%s),buildNo:12"\ngulp --cordova "build ios" --no-build\n\n# build prod version\ngulp build --env=prod --res=prod --buildVars="buildTime:$(date +%s),buildNo:12"\ngulp --cordova "build ios" --no-build\n<\/code><\/pre>\n
At this point, I like to explicitly separate the web app build from the Cordova build, so it doesn’t get messy, and it’s a little more apparent what we’re actually doing. Don’t forget the --no-build<\/code> option when running the Cordova part of your build, or it will implicitly run gulp build<\/code> and overwrite your previous gulp build<\/code> without any of the options you supplied earlier.<\/p>\n
Deliver<\/h3>\n
Now that you have built two runnable apps, how do you get them to your customer for testing purposes?<\/p>\n