Intro to Ionic Framework

  • February 24th, 2016

This was originally a companion post to a talk I gave at the Colorado Springs JavaScript meetup. Here is the slideshow presentation I used.

This tutorial uses Checkmate, a simple jQuery plugin that creates step-by-step guides out of HTML checkbox inputs. “Check” it out here.

 

Introduction

The objective of this post is to allow someone to dive into the Ionic Framework. We do this by getting our hands dirty creating an example project. Let’s begin!

 

Creating Our First Project

First things first: you’ll need Node and npm to work with Ionic. Don’t have these? Get them.

 

1. Install Cordova & Ionic:

npm install -g cordova ionic
 

2. Generate New Project Using Ionic’s Command Line Interface (CLI):

We are starting an Ionic project named cosExample based on the tabs starter project:

ionic start cosExample tabs

Hint: You can check out a number of starter projects over on the Ionic GitHub Repository. Any project prefixed with ionic-starter-[project] can be used with the ionic start [your-project] [project] syntax.

 

If everything went right, the CLI has generated your app scaffolding in a new cosExample directory. Ionic should have also went ahead and automatically added the iOS platform to your project.

 

3. So, let’s explore what the new project looks like:

cd cosExample && ls
bower.json	gulpfile.js	ionic.project	platforms	scss
config.xml	hooks		package.json	plugins		www

Let’s break it down:

  • platforms directory will be host to your platform builds – which is right now, just iOS.
  • plugins is where our Cordova plugins live.
 

Gulp

We also have a gulpfile in our root directory. The gulpfile is setup by default to process sass from the scss but we will be ignoring this for now.

Not familiar with Gulp? Learn more.

 

Bower

We will be using Bower for package management.

Bower is set up “out of the box” with Ionic. By default, Bower packages are put in a bower_components directory. With Ionic however, our packages will be installed in www/lib.

If you are familiar with AngularJS projects, you can think of www as the typical app directory. This is where you will be doing the vast majority of your work.

Speaking of which, you may want to check out the Gulp- or Grunt-based Yeoman generators and boilerplates below in the Additional Resources section. These are quite fleshed out (testing, uglification, concat files, etc) but for the sake of simplicity, we will continue with this CLI-generated app.

If you are not familiar with Bower, learn more.

 

The Serve Command

The serve command allows us to serve our app to your web browser. Let’s give this a try.

4. Now, let’s serve up to our browser:

ionic serve

By default, the ionic serve command uses live reload, a nice feature especially when you are scaffolding out your app.

 

Adding Native Plugins

Okay, obviously this app doesn’t really do anything. For the sake of an easy example, let’s grab device information via a Cordova plugin and display it.

 

ngCordova

ngCordova is basically a set of AngularJS services that wrap Cordova plugins in Angular modules, which means they can be mocked. They also almost always use promises, which is nice.

5. Add ngCordova to the application using Bower:

bower install ngCordova
 

6. Add our script to www/index.html above the cordova.js script:

<script src="lib/ngCordova/dist/ng-cordova.js">
<script src="cordova.js">

7. Inject Dependency – www/js/app.js:

angular.module('myApp', ['ngCordova'])
 

Device Plugin

Let’s the right plugin for grabbing device data (by checking ngCordova docs). Looks like Device will do the trick.

8. Add Cordova Device Plugin:

cordova plugin add cordova-plugin-device

Note: You will probably find that the device plugin has already been installed, and that’s okay, no harm.

 

Adding Application Code

Now we have installed our connection with the native world with the Cordova plugin – let’s add our application code:

9. Add a state to our AngularUI-router-based $stateProvider – located in www/js/app.js:

.state('tab.device', {
    url: '/device',
    views: {
      'tab-device': {
        templateUrl: 'templates/tab-device.html',
        controller: 'DeviceCtrl'
      }
    }
  })

10. Add a controller and logic – www/js/controllers.js:


.controller('DeviceCtrl', function($cordovaDevice, $ionicPlatform, $scope) {

  // Wrapping in callback function to wait for device to become ready:
  $ionicPlatform.ready(function() {
    // $cordovaDevice is one of the few ngCordova modules that doesn't use promises:
    $scope.myDevice = $cordovaDevice.getDevice();

    // Show off our console logging in the emulator:
    console.log(JSON.stringify($scope.myDevice));
  });
})

Note: Ionic starter projects lump all their like modules (controllers, services, etc) into a single file. This is not considered best practice. Generally, we want to do one file per module. Check out this AngularJS Style Guide.

11. Add HTML – create a device template (www/templates/tab-device.html):


<ion-view view-title="Device">
  <ion-content>
    <ion-list>
      <ion-item ng-repeat="(key,value) in myDevice">
        <p>{{ key }}: {{ value }}</p>
      </ion-item>
    </ion-list>
  </ion-content>
</ion-view>

Note the elements created by Ionic’s AngularJS directives (ion-view, ion-content, etc.)…

12. Add HTML to the tabs – www/templates/tabs.html:


  
  <ion-tab title="Device" icon-off="ion-ios-monitor-outline" icon-on="ion-ios-monitor" href="#/tab/device">
    <ion-nav-view name="tab-device">
  </ion-tab>
 

Emulate Command

And, lucky number step 13…

13. Run the Emulator:

ionic emulate ios -l -c

Tip: Use the -l and -c flags for LiveReload and console logging right in your emulator. Slick.

If all goes well – you should get a list of device properties when you head over to the “Device” tab in the app.

 

Conclusion

Okay so, cool, but this is a pretty bare bones, boring app – but I hope it’s helped to familiarize yourself a little bit with the tools and structure you will be using to create a sweet, sweet Ionic app.

Questions, comments, etc. Leave ’em! Below is a list of additional resources that hopefully will help you on your way.

 

Additional Resources

 

AngularJS

ngCordova
AngularJS Style Guide
The Ultimate AngularJS & Ionic Performance Cheatsheet
AngularJS Learning Resources (GitHub Repo)
ngDocs – Documentation system based on jsDoc

 

(Alternative) Code Generators / Scaffolding

Yeoman Generator for Gulp-based Ionic Projects
Gulp-based Ionic Project Seed
Yeoman Generator for Grunt-based Ionic Projects

 

Testing & Emulation

Karma Cordova Launcher
ngCordova Mocks
AngularJS Unit Testing Best Practices
Ripple Emulator
Genymotion (Better Android Emulation)

Tags: , , , , , , , , ,

One response to “Intro to Ionic Framework”

  1. […] the full article, click here. @8EJ3: “Introduction to the Ionic Framework: (@ionicframework) #Ionic #JavaScript […]

Leave a Reply