Ionic 2 | Tutorial | Let’s Create Our First Application

http://www.gajotres.net/ionic-2-tutorial-lets-create-our-first-application/

By Gajotres -Last updated on March 31st, 2016

In my previous article, I showed you an anatomy of Ionic 2 page. Now let’s do something with that knowledge, we’re going to create our first Ionic 2 application, and we’re going to create something useful. Our application will use a Master-Detail pattern and REST protocol (We will use it to query international movie database).

I don’t know if you remember (for those of you who read my blog before), but I did the same thing with Ionic 1. It’s even the same app we’re going to create today. You can find it here: Creating your first Ionic Framework application. This way you can compare old example with a new one.

Note: If this tutorial was helpful, need further clarification, something is not working or do you have a request for another Ionic post? Furthermore, if you don't like something about this blog, if something is bugging you, don't like how I'm doing stuff here, again leave me a comment below. I'm here to help you, I expect the same from you. Feel free to comment below, subscribe to my blog, mail me to dragan.gaic@gmail.com, or follow and mention me on twitter (@gajotres). Thanks and have a nice day!

PS. If you want my help, if possible (even if it takes you some time to do that), create a working example I can play with. Use Plunker for AngularJS based questions or jsFiddle for jQuery/jQuery Mobile based questions.

Ionic 2 is causing you problems? Are you struggling to make it work? Trust me, I wasn’t in any better situation. If you require more information beyond the subject of this article you will probably find it in a list below. Take a look; if there’s a topic not covered there, leave me a comment and I’ll cover it.

Click here if you want to see a list of topics covering Ionic 2 framework

Introduction to Object Oriented JavaScript

Ionic 2 Tutorials

Preparations

Before we can begin, make sure you have everything preconfigured for Ionic 2.

You should have these:

Android Environment (or iOS if you’re working on a MacOS)
nodeJS
Ionic 2
Cordova

Find more information here: IONIC 2 | INSTALLATION GUIDE if you don’t have a previous Ionic 2 installation or if you have never read my previous articles on this topic.

1. Update Ionic & Cordova

You need to have a latest nodeJS version, without it, you’ll not be able to install/update Cordova and Ionic appropriately.

If you have a previous Ionic/Cordova installation make sure its up to date, older versions may not work with this tutorial. Though latest versions may also mess things up:

npm install
-g cordova ionic@2.0.0-beta.22

or you can even do it like this:

npm update -g cordova ionic@2.0.0-beta.22

I will remove beta keyword once Ionic 2 reach RC status.

Warning: Ionic2 is still in beta so the final implementation may differ from this code. I will update this article if and when that happens.

2. Create A New Project

ionic start Ionic2FirstApp blank --v2
cd 
Ionic2FirstApp

Open app directory and remove all content from a directory called pages but don’t delete it. Somewhere below you’ll find a link to GitHub repo holding a working example (or you can copy past provided code).Download zipped project repo folder, copy app and www directory and past it into a newly created folder.

Warning: Since some of you never worked with Ionic CLI. From this point and further, every time I tell you to execute something, do that inside a project folder.

Add Android platform:

ionic platform add android

MacOS users can also add iOS platform:

ionic platform add ios

3. Install Cordova Whitelist Plugin

Install Cordova Whitelist Plugin:

cordova plugin add cordova-plugin-whitelist

Open www folder and add this security meta tag to index.html file:

<meta
http-equiv="Content-Security-Policy"
content="default-src *; script-src 'self' 'unsafe-inline' 'unsafe-eval' *; style-src  'self' 'unsafe-inline' *">

Be careful, don’t do this step before you add designated platform(s) (Android/iOS).

GitHub - Whitelist

Install Whitelist plugin only if you’re using Cordova 4.0 +. Without it, you’ll receive “Application Error: There was a network error.” error.

Example

Before we start, you can find a working example at the Ionic View service. Search for an ID 8A865059.

Or you can look at this embedded example:

Embeded example:

Ionic Page Navigation

Unfortunately, I can’t show you an embedded working example like before. For some reason, this code works just fine when executed on my local Windows-based Apache server, but fails on my Linux-based hosted Apache server. Hopefully, I’ll find a solution for this problem.

Source Code

Update: 31.03.2016 (March 31st) - Article and example are updated to match changes made to Ionic Beta 22 version

If GitHub repo is not available, and you can only use code provided below, this is what project folder looks like (image was taken from Sublime text editor):

index.html

<!DOCTYPE
html>
<html
lang="en">
<head>
  <title>Ionic</title>
  <meta
charset="UTF-8">
  <meta
name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
  <meta
http-equiv="Content-Security-Policy"
content="default-src *; script-src 'self' 'unsafe-inline' 'unsafe-eval' *; style-src  'self' 'unsafe-inline' *">
  <link
ios-href="build/css/app.ios.css"
rel="stylesheet">
  <link
md-href="build/css/app.md.css"
rel="stylesheet">
  <link
wp-href="build/css/app.wp.css"
rel="stylesheet"> 
</head>
<body>
 
  <ion-app></ion-app>
 
  <!-- cordova.js required for cordova apps -->
  <script
src="cordova.js"></script>
  <!-- Zone.js and Reflect-metadata  -->
  <script
src="build/js/angular2-polyfills.js"></script>
  <!-- the bundle which is built from the app's source code -->
  <script
src="build/js/app.bundle.js"></script>
</body>
</html>

The main index.html is part of a www directory and it will always look the same.

Only thing worth pointing out is:

<ion-app></ion-app>

That component will initialize our application.

app.html

<ion-nav
id="nav"
[root]="rootPage" #content swipe-back-enabled="false"></ion-nav>

This line is the most important part of any Ionic 2 application. ion-nav component handles application navigation and history.

Take a careful look at this property:

[root]="rootPage"

This is a special way AngularJS 2 allows us to access navigation directly from application classes. In this case, an application is referencing root property to rootPage variable. In the next section, you’ll learn how to access nav component through this variable.

app.js

import
'es6-shim';
import
{App, IonicApp, Platform} from 'ionic-angular';
import
{StatusBar} from 'ionic-native';
import
{MovieListPage} from './pages/movie-list/movie-list';
 
@App({
  templateUrl:
'build/app.html',
  config: {}
})
 
class
MyApp {
  static
get parameters() {
    return
[[IonicApp], [Platform]];
  }
 
  constructor(app, platform) {
    this.app = app;
    this.platform = platform;
    this.initializeApp();
 
    this.rootPage = MovieListPage;
  }
 
  initializeApp() {
    this.platform.ready().then(() => {
      StatusBar.styleDefault();
    });
  }
}

I will not go into great details here; if you want to learn more take a look at my previous article.

First, root component needs to import everything required for successful application initialization:

import
'es6-shim';
import
{App, IonicApp, Platform} from 'ionic-angular';
import
{StatusBar} from 'ionic-native';
import
{MovieListPage} from './pages/movie-list/movie-list';

Connect the root component model with a view (app.js with app.html) and initialize a class:

@App({
  templateUrl:
'build/app.html',
  config: {}
})
 
class 
MyApp {

Use a class constructor to define an application root page:

this.rootPage = MovieListPage;

A variable rootPage is the same one we talked about in previous section (app.html). MovieListPage is imported in app.js second line.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

http://www.gajotres.net/ionic-2-tutorial-lets-create-our-first-application/2/

app.core.scss

@import "../pages/movie-list/movie-list";

@import "../pages/movie-info/movie-info";

These two lines are easy to understand. Application will use them to import movie-list page and movie-info page SCSS styles.

movie-list.html

<ion-navbar *navbar>
  <ion-title>Movie List</ion-title>
</ion-navbar>

<ion-content padding>
  <ion-list>
    <ion-header>      
      <ion-item>
        <ion-input type="text" placeholder="Search a movie..." (input)="searchMovieDB($event, searchKey)"></ion-input>
      </ion-item>
    </ion-header>

    <ion-item *ngFor="#movie of movies" (click)="itemTapped($event, movie)">
      <ion-avatar item-left>
        <img src="https://image.tmdb.org/t/p/w92{{movie.poster_path}}"/>
      </ion-avatar>
      <h2>{{movie.original_title}}</h2>
      <p class="item-description">{{movie.overview}}</p>
    </ion-item>
  </ion-list>
</ion-content>

This page is an application root page.

As you can see it has a nav-bar component; top or bottom depending on a underlaying platform.

Because this application doesn’t have a side menu nav-bar component will only hold a page name.

The other major component is a page content and it can be found inside an ion-content component. If you have a previous Ionic 1 experience, you’ll notice how this semantic is very similar to the old one.

Application will start with an input box we can use to enter a movie name:

    <ion-header>      
      <ion-item>
        <ion-input type="text" placeholder="Search a movie..." (input)="searchMovieDB($event, searchKey)"></ion-input>
      </ion-item>
    </ion-header>

Notice a new way of event handling in AngularJs:

(input)="searchMovieDB($event, searchKey)

A function searchMovieDB is part of a movie-list class, you’ll see it in a next section.

When we enter a movie name, each time we add a new letter application will query a list of movie names matching entered value.

Query result will show inside an ion-item component.

<ion-item *ngFor="#movie of movies" (click)="itemTapped($event, movie)"> 

</ion-item>

Here we can see another new AngularJs 2 syntax:

*ngFor="#movie of movies"

ngFor is an AngularJs 2 replacement for ng-repeat. It will loop through movies array, and during each loop, an element will be added to movie variable.

When we click/tap this ion-item element it will trigger a click event calling a itemTapped function. One of the itemTapped function parameters is previously mentined movie variable. You should already know this, itemTapped function is defined inside a movie-list class.

ngFor is also a new Angular 2 syntax, several versions ago it was ng-for; so be careful while googling Ionic 2 examples.

ion-item holds a template that application will use to display query results:

<ion-avatar item-left>
    <img src="https://image.tmdb.org/t/p/w92{{movie.poster_path}}"/>
</ion-avatar>
<h2>{{movie.original_title}}</h2>
<p class="item-description">{{movie.overview}}</p>

The same templating system was used in a previous Ionic implementation.

Last but not least, this page is the first part of a Master-Detail pattern.

movie-list.js

import {Page, NavController} from 'ionic-angular';
import {MovieService} from '../services/MovieService';
import {MovieInfo} from '../movie-info/movie-info';
 
@Page({
  templateUrl: 'build/pages/movie-list/movie-list.html',
  providers: [MovieService]
})
 
export class MovieListPage {
  static get parameters() {
    return [[NavController], [MovieService]];
  }

  constructor(nav, movieService) {
    this.nav = nav;
    this.movieService = movieService;
  }
 
  searchMovieDB(event, key) {
    if(event.target.value.length > 2) {
      this.movieService.searchMovies(event.target.value).subscribe(
        data => {this.movies = data.results; console.log(data);},
        err => this.logError(err),
        () => console.log('Movie Search Complete')
      );
    }
  } 
 
  itemTapped(event, movie) {
    this.nav.push(MovieInfo, {
      movie: movie
    });
  }
}

Again, import necessary components:

import {Page, NavController} from 'ionic-angular';
import {MovieService} from '../services/MovieService';
import {MovieInfo} from '../movie-info/movie-info';

MovieService is a class holding REST call functions. I should also mention that this service doesn’t have an HTML component; we’ll talk more about it later.

On the other hand, MovieInfo is a page we’re going to use to show selected movie details. It’s also the second part of Master-Detail pattern.

Connect this class with an appropriate HTML file:

@Page({
  templateUrl: 'build/pages/movie-list/movie-list.html',
  providers: [MovieService]
})

providers keyword is required so Angular can know how to create and inject an object of type MovieService. This is how AngularJS 2 handles dependency injection.

This code will not work without that keyword; you would receive this error:

EXCEPTION: No provider for MovieService! (MovieListPage -> MovieService)

Import MovieService to movie-list class:

  static get parameters() {
    return [[NavController], [MovieService]];
  }

  constructor(nav, movieService) {
    this.nav = nav;
    this.movieService = movieService;
  }

Each time we enter a new letter into movie-list page search input, it will trigger function:

  searchMovieDB(event, key) {
    if(event.target.value.length > 2) {
      this.movieService.searchMovies(event.target.value).subscribe(
        data => {this.movies = data.results; console.log(data);},
        err => this.logError(err),
        () => console.log('Movie Search Complete')
      );
    }
  }

When we enter 3 or more characters a function will call a MovieService service function searchMovies.

Take a special look at the subscribe function used after searchMovies. It is used to handle async REST query made inside a searchMovies function. This way, when REST call (inside a MovieService) finishes, the result will be added to this.movies variable. This may look strange but trust me, this solution is much easier than what we used to have in Angular 1.

itemTapped function is called when we click/tap list element:

  itemTapped(event, movie) {
    this.nav.push(MovieInfo, {
      movie: movie
    });
  }

This is also a good and easy example of how Ionic 2 handles page navigation. You should no longer worry about routing. Simply use push function to change a page and add a new page to the navigation history or a pop function to remove a page from the navigation history.

The push function will accept two parameters. The first one is a page we’re trying to transition too and the second one is an object holding data we’re trying to pass to that page.

In this case, our application is sending a movie object holding all information about a selected movie.

MovieService.js

import {Http} from 'angular2/http';
import 'rxjs/add/operator/map';

export class MovieService {  
	static get parameters() {
		return [[Http]];
	}

	constructor(http) {
		this.http = http
	}	

	searchMovies(movieName) {
		var url = 'http://api.themoviedb.org/3/search/movie?query=&query=' + encodeURI(movieName) + '&api_key=5fbddf6b517048e25bc3ac1bbeafb919';
		this.response = this.http.get(url).map(res => res.json());
	  return this.response;
	}
}

As you can see, this is a very simple service class. Again, we’re importing components necessary for the REST communication:

import {Http} from 'angular2/http';
import 'rxjs/add/operator/map';

movie-info.js

import {IonicApp, Page, NavController, NavParams} from 'ionic-angular';

@Page({
  templateUrl: 'build/pages/movie-info/movie-info.html'
})

export class MovieInfo {
  static get parameters() {
    return [[IonicApp], [NavController], [NavParams]];
  }

  constructor(app, nav, navParams) {
    this.nav = nav;
    this.movie = navParams.get('movie'); 
    console.log(this.movie); 
  }
}

Here’s the second part of Master-Detail pattern.

This page will display selected movie information and poster.

There’s only one thing worth mentioning in this class:

this.movie = navParams.get('movie');

This is how an application can handle data sent from the previous page via push function.

movie-info.html

<ion-navbar *navbar>
  <ion-title>Movie Details</ion-title>
</ion-navbar>

<ion-content>
  <div *ngIf="movie" class="selection">
    <ion-card>
      <ion-item>
        <ion-avatar item-left image-large>
          <img src="https://image.tmdb.org/t/p/w92{{movie.poster_path}}"/>
        </ion-avatar>
        <ion-item-content class="movie-title-data">
          <h1>{{movie.title}}</h1>
          <p>{{movie.release_date}}</p>
        </ion-item-content>
      </ion-item>

      <ion-item>
        <icon document item-left></icon>
        <h2>Overview</h2>
        <p class="item-description">{{movie.overview}}</p>
      </ion-item>
      <ion-item>
        <icon bookmark item-left></icon>
        <h2>Average Vote</h2>
        <p>{{movie.vote_average}}</p>
      </ion-item>    
    </ion-card>
  </div>
</ion-content>

Finally here’s a movie-info.html page.

It’s just a template application is using to display selected movie information.

Deployment

Next step, build our application:

ionic build android

Be careful here, this step may break if you’re behind a firewall. The first execution will take a long time, so be patient.

Finally:

ionic run android -l -c -s

Download The Code

Working GitHub repo link can be found below:

GitHub

What to read next

IONIC 2 | Making REST HTTP Requests Like a Pro

Who Am I?

Between working as a senior Java developer in one of the largest insurance companies in the world and traveling, in my free time, I work as a professional mobile development adviser. I'm also a major jQuery Mobile supporter back at StackOverflow and a forum moderator at the official Ionic Framework forum.

Blogs worth reading

If you're here looking for information related to the Ionic Framework, you will also like these blogs:

Andrew McGivery Blog