What is ionic – Getting started guide for beginners

Welcome to the 21st century, where you can write javascript to create not only web pages, but also mobile applications. In this guide I will present the growing in popularity tool ionic and how to use it’s CLI to build your app.

Ionic is a platform, or I should say, a cluster of platforms for building hybrid apps. Ionic is built on top of Angular.js. It contains some features that are 3rd party modules for Angular.js such as ui-router. It also encompasses some directives that facilitate the mobile interface development and is dependent on cordova and Angular.js. There are some strictly ionic plugins connected with the native part of the hybrid app such as the keyboard plugin. There is already a number of strictly ionic front-end only plugins/directives. Ionic makes it easy to develop an app for ios and android, as it has included default themes with native look. (We will look at material design later, the current Android native look is based on Android 4+) Ionic has also a CLI tool coupled with Cordova CLI.

Requirements

To create or edit an ionic application you will need to install a certain number of additional software and CLI tools. We need to start with installing node.js and npm. Cordova also migrated to npm as well most of its plugins. Assuming we are building an Android application we will need to install Java and Android SDK. We can proceed with installing globally Cordova CLI with the command:

npm install cordova -g

The same way we install ionic CLI:

npm install ionic -g

I use standard freeware editors to create and edit my ionic applications, such as brackets, Atom, Sublime and other. Netbeans has support for Cordova apps, but I haven’t tried it yet. Another possibility is to use the Android IDE, based on Webstorm. Brackets and Sublime have additional plugins for Angular and ionic intellisense.

Initial Setup

Creating a new project can be done by running one of next commands in the console:

ionic start myApp blank – creates a sample empty application
ionic start myApp tabs – creates a sample app based on tabs navigation
ionic start myApp sidemenu – creates a sample app base on side menu navigation

Installing platforms

$ cd myApp
$ ionic platform add android
$ ionic browser add crosswalk
$ ionic build android
$ ionic run android

and for ios

$ cd myApp
$ ionic platform add ios
$ ionic build android
$ ionic emulate ios

ionic will install statusbar plugin and keyboard by default

cordova plugin add cordova-plugin-ionic-keyboard
cordova plugin add cordova-plugin-statusbar

You can install plugins with Cordova CLI

cordova plugin add cordova-plugin-camera

The good news is that you can actually save the state with both CLI’s. The advantage of the ionic CLI is that it actually saves that you have installed crosswalk and some other stuff related to the ionic services features, like app id in ionic’s system and the crosswalk version.

Saving/Restoring state

• The cordova way to save

cordova plugin save

and

cordova platform save

• The cordova way to restore

cordova prepare

• The ionic way to save

ionic state save

• The ionic way to restore

ionic state restore

So far so good

Since our apps will be Cordova based, this means that they will work with the default webview of the OS. We all know that the default Android view is not quite the same as the browser and even more, it is far away from the performance and HTML 5 APIs support of the Chrome browser. To change this, we would like to use the so called Crosswalk project. https://crosswalk-project.org/

Crosswalk

You may ask what Crosswalk is. Well, it’s an embedded Chrome webview replacing the default one in Android 4+. Basically in Android 5 you might not needed it. So what? Having Chrome webview gives the web technologies based UI to perform a lot better and gives accessibility to edge HTML5 APIs and CSS3 features, whose usage might not be possible in older Android versions. It also gives you possibility to debug live from Desktop Chrome Dev Tools which is a big advantage in comparison with the Android IDE Logcat or Eclipse.

Apple is falling back behind, the company developed a replacement for their default UIWebView. It is called WKWebView, which has a lot better support of the HTML 5 features. There is also a developed plugin for Cordova, which we could use if we want to support modern iOS devices.
Both plugins can be found in NPM repository. So far, I’m not sure if there is a CLI command for Ionic to install WKWebview, but it can be done via Cordova CLI.

https://www.npmjs.com/package/cordova-plugin-crosswalk-webview
https://www.npmjs.com/package/cordova-plugin-wkwebview

Folder structure

Everything looks like we are set up and ready to create our ionic application. Actually, there is one issue that I noticed. I see a problem with the default provided file structure of the ionic starter apps.
https://github.com/driftyco/ionic-starter-tabs/tree/master/js

Currently you will see that all the services and all the controllers are in one file – services.js and controllers.js. After reading bunch of guidelines for structuring Angular app and seeing a need of a build process, our team agreed that we need to separate things up. First of all, the www folder is used as a source for the hybrid app. The code inside should be production ready after the build process – this include minification, concatenation and obfuscation. We create another folder called dev, where we implement folder-by-feature file structure where we build our app https://github.com/johnpapa/angular-styleguide#style-y152. In many cases there could be a difference with the suggested example – layout could be called main, or we could create folder-by-view with additional folders for common code like directives and maybe services. This is done for readability, fast navigation and code organization.

Generally I prefer placing templates and controller related to them in one folder. The classic way of declaring dependencies for the controllers, services and directives often provokes errors like missing one or more dependencies. Another way to declare the dependencies in the $inject clause per component, but this can also lead to same errors. To avoid such mistakes I use one feature that comes with the build process, I rely on our build script to inject dependencies, by just adding /* @ngInject */ before controllers, services and other dependency injectable objects. The controllers and routes will be structured with controller As ‘vm’ https://github.com/johnpapa/angular-styleguide#style-y032 and other recommended styles for Angular components from John Papa.

Prepare for build

Our ionic app already has a gulp build script, so we are going to use Gulp and make heavy modifications on the script. For the purpose of our build script we will use a number of gulp modules, that can be found on http://npmjs.org

• gulp – the gulp CLI;
• gulp-cheerio – this is a plugin for gulp which allows you to manipulate HTML and XML files using cheerio (somewhat jquery on server);
• gulp-concat – we will use it to concat files;
• gulp-dom-src – can create a stream of files from an HTML file, reading it’s script and/or links tags. This frequently is used when we use dependencies that don’t have scss file in the source folder and we need to manually include them in our main html file;
• gulp-flatten – basically used to flatten your file structure, helps with fixing the relative paths when moving content to new resulted folder. It helped us to manage the fonts and the images included in the main scss file;
• gulp-html2js – a plugin that helps you to generate Angular.js modules from html templates;
• gulp-minify-css – as the names says, it will minify the css files from a stream;
• gulp-ng-annotate- this plugin will look for @ngInject and injects automatically the dependencies that were mentioned in your constructor function for directives, services and controllers;
• gulp-rename – renames files;
• gulp-replace – replace strings in files;
• gulp-sass or gulp-ruby-sass – You can use one of them for building the main SCSS file, you need to keep in mind that the first is C/C++ based and is not the same implementation as the ruby based, some things might not be implemented in the C/C++ version;
• gulp-uglify – uglify and minify javascript files;
• run-sequence – runs a sequence of gulp tasks in the specified order;
• shelljs – we use it to check if we have the required dependencies to run ionic, more precise to check if we have Git and Android SDK installed.

I’m not going deeper in how to write the build script, this will be presented as another topic.

Preview the app in the browser

Finally, we can see the results of our work in the browser without building an executable for our phone. There is only one drawback – you can’t check if your native plugins are working.
You just need to run ionic serve, this will open a browser window or tab. With the help of the development tools you can emulate the device you want to test on.

Facebook integration on android

This was one of the challenges. Facebook and android made it especially hard to do it.
The problem is that Facebook requires a hash key of your application. As a base of the process I used those resources:
https://developers.facebook.com/docs/facebook-login/android

In the development stage you can use the default androiddebugkey. You will not need to run the build with –release flag in order to be signed. We can export this keystore by entering in the command line:

keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%.androiddebug.keystore | openssl sha1 -binary | openssl base64

The password required is the default “android”, if you haven’t changed it.
Using the non release(debug) build we will have the ability to inspect the app via chrome://inspect.

To generate a keystore you have to run this command line

keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000

There are some additional step you need to make. You need to export the generated by the above command, hash key with the following command line:

keytool -exportcert -alias my-release-key -keystore %HOMEPATH%.androidmy-release-key.keystore | openssl sha1 -binary | openssl base64

The hash printed in the console is the one you need to put in the facebook application properties.

Another addition is that ionic actually changed the hybrid app build to use gradle, which uses a different format of the building properties data, required to build a signed application. In the earlier versions it was using ant. I think this change is related to how Android apps build now. You will need this key when you decide to upload your app to the Google play store. For more detailed explanation you can check ioni’s guide of publishing an app – http://ionicframework.com/docs/guide/publishing.html

so for earlier versions we had ant.properties

key.store.password=example
key.alias.password=example
key.store=C:\Users\your.name\.android\my-release-key.keystore
key.alias=my-release-key

The new gradle format requires a file release-signing.properties with the following format

storePassword=example
keyPassword=example
storeFile=C:\Users\your.name\.android\my-release-key.keystore
keyAlias=my-release-key

For more security it is better to not include the password in the release-signing.properties, you will be prompted to input one, when building. Also keep secure your keystore, do not include it in the source control repository or in the folder structure of the project.

Building for release

When we are ready to upload to Google Play we need to build the app the the following line:

ionic build android –release

It will use our generated keystore. Keep it somewhere secure! Do not include it in the source of the app or somewhere in the repository!

Eventually when we need to release to the Play store, we will need to run through the steps 3,4 and 5 from the https://developer.android.com/tools/publishing/app-signing.html guideline.