Getting started with Ionic 2 Ionic 2

Getting started with deepstreamHub is easy and takes less than ten minutes. However, if you have any questions, please get in touch.

This getting started guide will walk you through integrating deepstream in Ionic (v2x).

Ionic is built on top Angular so you will see a lot of borrowed code from the Angular guide. This means we might interchange the words Angular and Ionic.

You will also learn how to implement the three deepstream core concepts: Records, Events and RPCs.

First, let's start by creating a free deepstreamHub account:

Create a free account and get your API key

deepstream provides a JavaScript library which helps in interacting with your deepstreamHub server.

Create an Ionic App

Install the Ionic CLI tool globally and use the tool to scaffold a new app:

# Install CLI tool
npm install -g ionic
# Scaffold a new app
ionic start ds-ionic tabs --v2

tabs is the template we want to use and --v2 is the preferred Ionic version

Connect to deepstreamHub and log in

After you have successfully created an Angular app install the deepstream and the JS-client library in your new project:

npm install deepstream.io-client-js --save

We need to import deepstream to our Ionic app:

import * as deepstream from 'deepstream.io-client-js';

Get your app url from the dashboard and establish a connection to deepstreamHub using an Angular service:

@Injectable()
export class DsService {
  get dsInstance() {
    return deepstream('<YOUR APP URL>').login()
  }
}

The login method can take credentials if authentication is configured.

Records (realtime datastore)

Creating a new record or retrieving an existent one works the same way:

var myRecord = ds.record.getRecord( 'test/johndoe' );

Values can be stored using the .set() method:

myRecord.set({
    firstname: 'John',
    lastname: 'Doe'
});

Let's set up two-way bindings with an input field. Whenever a path within our record changes (e.g. firstname), we want to update the input. Whenever a user types, we want to update the record.

Let's see a contexual example:

@Component({
  selector: 'page-record',
  template: `
  . . .
      <ion-list>

    <ion-item>
      <ion-label floating>First Name</ion-label>
      <ion-input type="text" [ngModel]="firstname" (ngModelChange)="handleFnameChange($event)"></ion-input>
    </ion-item>

    <ion-item>
      <ion-label floating>Last Name</ion-label>
      <ion-input type="text" [ngModel]="lastname" (ngModelChange)="handleLnameChange($event)"></ion-input>
    </ion-item>

  </ion-list>
  . . .
  `
})
export class RecordPage implements OnInit{
  firstname;
  lastname;
  record;

  constructor(private dsService: DsService){}

  ngOnInit() {
    this.record = this.dsService.dsInstance.record.getRecord('test/johndoe')
    this.record.subscribe((val) => {
      this.firstname = val.firstname;
      this.lastname = val.lastname;
    })
  }

  handleFnameChange(val){
    this.record.set('firstname', val);
  }
  handleLnameChange(val) {
    this.record.set('lastname', val);
  }
}

The subscribe method is used to listen for updates and update the inputs accordingly. The method is called in the ngOnInit lifecycle hook so it can be setup once the component is loaded.

Events (publish-subscribe)

Clients and backend processes can receive events using .subscribe()

ds.event.subscribe( 'test-event', function( eventData ){ /*do stuff*/ });

... and publish events using .emit()

ds.event.emit( 'test-event', {some: 'data'} );

A little example:

@Component({
  selector: 'page-events',
  template: `
  ...
    <ion-content padding>
  <ion-list>
    <ion-item>
      <ion-label stacked>Value</ion-label>
      <ion-input type="text" [(ngModel)]="value"></ion-input>
    </ion-item>

    <ion-item>
      <button ion-button (click)="handleClick()">Send</button>
    </ion-item>
  </ion-list>

  <ion-list>
    <ion-list-header>Events Received</ion-list-header>
    <ion-item *ngFor="let event of eventsReceived">
      <ion-icon name="megaphone" item-left></ion-icon>

    </ion-item>
  </ion-list>

</ion-content>
...
  `
})
export class EventsPage implements OnInit {
  value = '';
  eventsReceived = [];

  constructor(private dsService: DsService){}

  ngOnInit() {
    this.dsService.dsInstance.event.subscribe('test-event', (val) => {
      this.eventsReceived.push(val);
    })
  }

  handleClick() {
    console.log(this.value)
    this.dsService.dsInstance.event.emit('test-event', this.value);
  }
}

An event is published anytime the button is clicked and the event.subscribe method listens for this publish action.

RPCs (request-response)

You can make a request using .make()

ds.rpc.make( 'multiply-numbers', { a: 6, b: 7 }, function( err, result ){
    //result === 42
});

and answer it using .provide():

ds.rpc.provide( 'multiply-numbers', function( data, response ){
    resp.send( data.a * data.b );
});

For example:

@Component({
  selector: 'page-rpc',
  template: `
    <ion-list>

    <ion-item>
      <ion-label fixed>Request</ion-label>
      <ion-input type="text" [(ngModel)]="requestValue"></ion-input>
    </ion-item>

    <ion-item>
      <ion-label fixed>Response</ion-label>
      <ion-input type="text" [(ngModel)]="responseValue"></ion-input>
    </ion-item>

    <ion-list-header></ion-list-header>

    <ion-item>
      <button ion-button (click)="handleClick()">Make</button>
    </ion-item>

  </ion-list>
  `
})
class RPCPage implements OnInit {
  requestValue = '3';
  responseValue = '7';
  displayResponse = '-';

  constructor(private dsService: DsService){}

  handleClick() {
          var data = {
                value: parseFloat(this.requestValue)
            };
        this.dsService.dsInstance.rpc.make( 'multiply-number', data, ( err, resp ) => {

              //display the response (or an error)
              this.displayResponse = resp || err.toString();
          });
  }

  ngOnInit() {
    this.dsService.dsInstance.rpc.provide( 'multiply-number', ( data, response ) => {
          // respond to the request by multiplying the incoming number
          // with the one from the response input
          response.send( data.value * parseFloat(this.responseValue) );
    })
  }
}

Clicking the button makes a request using rpc.make. The .make method is also responsible for handling the responses when they come back from the response provider which is the rpc.provide method.

Where to go next?

To learn how to use deepstreamHub with other frontend frameworks head over to the tutorial section. To learn how to use the JavaScript SDK with NodeJS rather than in a browser, head over to the getting started with NodeJS tutorial.