Building Ionic web apps with Wijmo and NPM

Notice: Code examples in this blog use Wijmo modules from the non-scoped ‘wijmo’ npm package. Beginning with Wijmo 2019 v1 release, Wijmo packages are also available in the @grapecity npm scope, and the use of these packages is the recommended for new applications. For the convenience of our customers, we continue publishing new Wijmo builds as non-scoped ‘wijmo’ packages as well.

Read more about Wijmo NPM Package Changes.

In this series, we'll show how you can use Wijmo with NPM and Webpack to create applications targeting the most popular JavaScript application frameworks. This blog focuses on Ionic, one of the most popular frameworks for building mobile apps, Ionic is focused on the look and feel, or the UI interaction, of an app. It's based on Angular and uses Cordova to provide access to native capabilities of specific devices, including sensors, data, network status, etc.

Blog series

1. Introduction to NPM and Wijmo

2. Angular

3. React

4. Vue.js

5. Ionic

In this tutorial, we won't get into the details of NPM, Webpack, or Ionic itself. All these tools are incredibly popular and thoroughly documented, and you can read our e-book on frameworks for a good overview. Instead, we'll focus on the task of adding Wijmo to simple applications written in Ionic.

The basic steps for creating and maintaining applications are the same in all frameworks:

• Install the appropriate CLI (Command-Line Interface utility) to generate, run, maintain, and deploy applications.

• Use the CLI to create the application.

• Use NPM to add Wijmo to the application.

• Import the components you want to use and add the appropriate markup.

Step 1. Create a new Ionic app

Follow these steps to create a new Ionic app and get it up and running:

You should see the app running in the browser. Let’s start editing the app. When you save changes, the browser will reload the app automatically.

Step 2. Add Wijmo modules

Open the “src/app/app.module.ts” file and add the Wijmo modules for the grid and chart:

// src/app/app.module.ts
import { NgModule, ErrorHandler } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { IonicApp, IonicModule, IonicErrorHandler } from 'ionic-angular';
import { MyApp } from './app.component';
import { AboutPage } from '../pages/about/about';
import { ContactPage } from '../pages/contact/contact';
import { HomePage } from '../pages/home/home';
import { TabsPage } from '../pages/tabs/tabs';
import { StatusBar } from '@ionic-native/status-bar';
import { SplashScreen } from '@ionic-native/splash-screen';

// import Wijmo modules
import { WjGridModule } from 'wijmo/wijmo.angular2.grid';
import { WjChartModule } from 'wijmo/wijmo.angular2.chart';

// apply Wijmo license key
import { setLicenseKey } from 'wijmo/wijmo';
setLicenseKey('your license goes here');

@NgModule({
  declarations: [
    MyApp,
    AboutPage,
    ContactPage,
    HomePage,
    TabsPage
  ],
  imports: [
    BrowserModule,
    IonicModule.forRoot(MyApp),
    WjGridModule,
    WjChartModule
  ],
  …
})
export class AppModule {}

In addition to importing the Wijmo modules we want, the code also applies a Wijmo license key to remove the evaluation watermark from the app. If you don’t have a license key, it’s OK to skip this step.

Now that the Wijmo modules have been referenced by the application module, we can use them in our component templates.

Step 3. Add data to the controls

Start by opening the “src/pages/home/home.ts” file and give the “HomePage” component some data for the controls:

// src/pages/home/home.ts
import { Component } from '@angular/core';
import { NavController } from 'ionic-angular';

// import Wijmo components
import { CollectionView } from 'wijmo/wijmo';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  constructor(public navCtrl: NavController) {
  }
  data = this.getData();
  getData() {
    var countries = 'US,Germany,UK,Japan,Italy,Greece'.split(','),
        data = [];
    for (var i = 0; i < countries.length; i++) {
      data.push({
        country: countries[i],
        sales: Math.random() * 10000,
        expenses: Math.random() * 5000,
        downloads: Math.round(Math.random() * 20000),
      });
    }
    return new CollectionView(data);
  }
}

Notice that getData returns a CollectionView rather than a regular array. The CollectionView class supports sorting, filtering, grouping, currency, and notifications. In this example, we'll use it as a data source for a grid and a chart.

Step 4. Add the Ionic controls to the app

To add the grid and the chart to the app, edit the “src/pages/home/home.html” file as follows:

<!-- src/pages/page/home.hmtl -->
<ion-header>
  <ion-navbar>
    <ion-title>Home</ion-title>
  </ion-navbar>
</ion-header>

<ion-content padding>
  <h2>Welcome to Wijmo in Ionic!</h2>
  <p>
    This starter project comes with simple tabs-based layout for apps
    that are going to primarily use a Tabbed UI.
  </p>
  <p>
    Take a look at the <code>src/pages/</code> directory …
  </p>
  <h4>Here are some Wijmo controls to help you get started:</h4>
  <div class="App-panel">
    <wj-flex-grid [itemsSource]="data">
    </wj-flex-grid>
    <wj-flex-chart [itemsSource]="data" [bindingX]="'country'">
      <wj-flex-chart-series [binding]="'sales'" [name]="'Sales'">
      </wj-flex-chart-series>
      <wj-flex-chart-series [binding]="'expenses'" [name]="'Expenses'">
      </wj-flex-chart-series>
      <wj-flex-chart-series [binding]="'downloads'" [name]="'Downloads'">
      </wj-flex-chart-series>
    </wj-flex-chart>
  </div>
</ion-content>

Notice the use of the wj-flex-grid, wj-flex-chart, and wj-flex-chart-series directives. These were imported from the grid and chart modules.

We're almost done. The last step is styling.

Step 5. Update the stylesheet

First, we'll add the “wijmo.css” file that contains the CSS rules for all Wijmo controls. There are several ways to add custom css files to the Ionic build process. In this example, we'll use the simplest one:

• Copy the “node_modules\wijmo\styles\wijmo.css” file to the application’s “src/assets/css” folder.

• Open the application’s “src/index.html” file and add this line:

<!-- src/index.hmtl -->
<link href="build/main.css" rel="stylesheet">
<link href="assets/css/wijmo.css" rel="stylesheet">

In addition to Wijmo’s standard CSS, we'll add some rules to customize our app. Open the “app/app.scss” file and add this code:

// app/app.scss
// http://ionicframework.com/docs/theming/

// App Global Sass
// --------------------------------------------------
// …
//
.App-panel {
    margin: 0 48pt;
    text-align: center;
    .wj-control {
        display: inline-block;
        width: 400px;
        height: 300px;
        vertical-align: top;
    }
}
.wj-flexgrid .wj-cell {
    padding: 8px;
    text-align: left;
}

Step 6. Test in the browser

Press ctrl+S to save the changes in all files and switch back to the browser to see the result:

Because the grid and the chart are bound to the same CollectionView, any changes made to the data in the grid are automatically reflected in the chart. For example, you may click the column headers to sort the data or edit some values using the keyboard.

Conclusion

Integrating Wijmo into modern JavaScript applications is just a matter of installing it with NPM and importing the components you want from the library.

Being able to use the exact same UI components on different frameworks makes things easier you work with two or more frameworks, or are planning to switch frameworks in the future.

Get Wijmo 2018 v1 now