Supercharge Your App Development with Ionic and AppBuilder

Ionic is slick. If you’re haven’t heard of it, Ionic is a UI framework that helps you build beautiful iOS and Android apps based on Cordova. Go ahead and peruse their UI components to see the powerful UIs you can build with a small amount of code.

But although Ionic’s UI is top notch, the library doesn’t give you the tooling and services you need to build high-quality hybrid applications. Need to test Cordova plugins? Need to build iOS apps on a Windows machine? Need help working with the insane iOS provisioning requirements? Ionic doesn’t help you solve these problems.

That’s where Telerik AppBuilder comes in, providing a series of tools and services to empower Cordova (and therefore Ionic) developers. AppBuilder makes testing on devices simple and integrating Cordova plugins a breeze. Builds are done in the cloud, so you don’t have to worry about managing Xcode or Android SDKs. And because AppBuilder doesn’t care how you build your apps, you can use Ionic or any UI framework you prefer.

Let’s see how AppBuilder makes Ionic development totally awesome.

Creating AppBuilder + Ionic apps

To show off all that AppBuilder can do, we’re going to build a small grocery list app using Ionic. To start you need to install AppBuilder, which — like Ionic — you can get from npm.

$ npm install -g appbuilder

AppBuilder provides several development options — from an in-browser IDE, to direct IDE integrations for Sublime Text and Visual Studio. Although I’m using the CLI for the purposes of this article, you can do anything I show in AppBuilder’s in-browser editor or Visual Studio Extension.

With the AppBuilder CLI you create new projects using the appbuilder create hybrid command. Use the command below to create a new project named “grocery-list”. Setting the --template=Blank option gives you a mostly empty app to use as a starting point.

$ appbuilder create hybrid grocery-list --template=Blank

This scaffolds a basic Cordova app in a “grocery-list” folder. Next, replace the new grocery list app’s index.html with the following basic Ionic app:

<html ng-app="grocery-app">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <title>AppBuilder + Ionic = <3</title>

    <script src="cordova.js"></script>
    <link href="http://code.ionicframework.com/1.0.0-beta.11/css/ionic.css" rel="stylesheet">
    <script src="http://code.ionicframework.com/1.0.0-beta.11/js/ionic.bundle.js">
    </script>
    <script>
        angular.module( "grocery-app", [ "ionic" ])
            .controller( "GroceryController", function( $scope ) {
            $scope.groceries = [
                "Bananas", "Apples", "Oranges", "Milk", "Eggs", "Bread",
                "Cereal", "Beef", "Napkins", "Cheese", "Peanut Butter"
            ];
        });
    </script>
</head>
<body ng-controller="GroceryController">
    <ion-header-bar class="bar-positive">
        <h1 class="title">Groceries</h1>
    </ion-header-bar>
    <ion-content>
        <ion-list>
            <ion-item ng-repeat="grocery in groceries" item="grocery">
                {{ grocery }}
            </ion-item>
        </ion-list>
    </ion-content>
</body>
</html>

This app shows the static list of groceries shown below:

grocery-app

The app is purposely simple to let you experiment with the functionality that AppBuilder offers. Let’s start with the AppBuilder simulators.

Using the AppBuilder simulators

AppBuilder includes a suite of simulators for iOS, Android, and Windows Phone. The simulators can be invoked using the AppBuilder in-browser IDE, from Visual Studio, from an installable Windows client, or from the AppBuilder CLI. Since we’re using the CLI here, you’ll want to use appbuilder simulate command to start the simulator.

$ cd grocery-list
$ appbuilder simulate

AppBuilder opens your app on a simulated device, and updates the app whenever you make code changes — which is great for fast prototyping and experimentation. For instance, I was initially confused about what the bar-positive Ionic class name did, so I toggled it a few times to see its effect. The workflow I used is shown below.

bar-positive

Ionic’s most recent update also offer this “live reload” behavior, but the AppBuilder simulators do so much more. Need to test different device types (phone vs. tablet)? Device rotation (portrait vs. landscape)? Connectivity (Wifi vs. 3G vs. offline)? The AppBuilder simulators do all this and more.

But the coolest feature is the simulators’ integrated debug tools, which — because the simulators are built on the Chromium Embedded Framework — are actually the full Chrome Dev Tools. Here I inspect Ionic’s header using the Dev Tools’ Elements panel:

dev-tools

This is cool, but we’re just getting started. Next let’s look at how easy it is to get your code on physical devices.

Companion apps

Simulators are nice, but they’re still just simulators. They can’t possibly emulate the actual environment mobile apps run on, which is important to accurately test your code. You also can’t hold a simulator in your hand, which is important for testing touch interactions.

To make this process super simple, AppBuilder provides companion apps for iOS, Android, and Windows Phone. As a developer, you download the companion app on your device (search for “AppBuilder” on your platform’s app store), connect your device via USB, and run a simple command.

For example, to send the grocery list app to USB-connected iOS and Android devices, you can use the following two commands:

$ appbuilder livesync ios --companion
$ appbuilder livesync android --companion

The screenshot below shows the app deployed to my physical iOS and Android devices. (Note that I’m using Reflector and Droid @ Screen to mirror my iPhone and Nexus 7, respectively.)

app-on-devices

The big win here is you don’t have to go through Apple’s arcane certificate and provisioning profile processes to run your code on a physical device in an actual UIWebView. You’ll still need to go through those processes eventually (assuming you want to submit to the App Store at some point), but the companion app provides a convenient testing mechanism you can use right away.

What’s even cooler is the companion apps provide the same LiveSync functionality that the simulators provide — all you have to do is run livesync with the --watch option.

$ appbuilder livesync ios --companion --watch
$ appbuilder livesync android --companion --watch

Now whenever you change your project’s code, those changes are automatically rendered on your USB-connected devices. Below I make changes to the heading of the grocery app and see them instantly rendered on my devices:

companion-livesync

Cordova testing

Another tricky issue with Ionic development is testing Cordova calls. Ionic’s documentation actually states that the Cordova script (<script src="cordova.js"></script>) “will be a 404 during development,” but that doesn’t have to be the case.

For example, suppose you want to build delete functionality into your grocery list, which Ionic makes super easy. All you have to do is add a show-delete attribute to your <ion-list> and an <ion-delete-button> element to the <ion-item>.

<ion-list show-delete="true">
    <ion-item ng-repeat="grocery in groceries" item="grocery">
        <ion-delete-button class="ion-minus-circled" ng-click="onItemDelete(grocery)"></ion-delete-button>
        {{ grocery }}
    </ion-item>
</ion-list>

The ng-click attribute on the <ion-delete-button> tells Ionic to run onItemDelete() every time you tap a delete button, and to pass it the grocery being deleted. The implementation of onItemDelete() is a simple function that removes the grocery from the array. Thanks to Angular the rest of the UI takes care of itself.

$scope.onItemDelete = function( grocery ) {
    $scope.groceries.splice(
        $scope.groceries.indexOf( grocery ), 1 );
}

The updated functionality is shown below:

delete-workflow

So where does Cordova come in? Let’s suppose that you want to add a confirmation dialog to this UI, so the user doesn’t accidentally delete an item. Ionic has some dialogs you could use, but Cordova provides a navigator.notification.confirm() API that shows the platform’s native confirmation dialog, which gives the app more of a native feel. Here’s the code that does that. (One weird thing to note is the index Cordova passes to the callback function is a one-based button index — where 1 is the OK button and 2 is the Cancel button.)

$scope.removeGrocery = function( grocery ) {
    $scope.groceries.splice(
        $scope.groceries.indexOf( grocery ), 1 );
};
$scope.onItemDelete = function( grocery ) {
    var message = "Are you sure you want to delete " + grocery + "?";
    navigator.notification.confirm( message, function( index ) {
        if ( index === 1 ) {
            $scope.removeGrocery( grocery );
            $scope.$apply();
        }
    });
}

This code would be hard to write in an Ionic-only environment, as the Cordova API is not available during development — but the AppBuilder companion apps can run this code as is. Better yet, the AppBuilder simulator also mocks these calls, so you can test your Cordova code there as well. Below I use this new code to delete a few items on (left to right) the AppBuilder simulator, an iOS device, and an Android device:

cordova-calls

Building native apps

The AppBuilder companion apps are powerful, but you can’t use them to test everything you need to build a hybrid app. If you want to test your app’s icons, permissions, or custom Cordova plugins, you need a truly native-built app (i.e. an installed .apk or .ipa). AppBuilder makes this easy by providing a build service that lives in the cloud — meaning, you don’t have to worry about managing XCode or Android SDKs. It also means you can build iOS apps on Windows without jumping through all sorts of hoops.

Need an Android .apk file? Run appbuilder build android. Need an iOS .ipa file? Run appbuilder build ios.

Ok, ok, there is one big caveat. For iOS builds to work in AppBuilder you need to become a registered iOS developer ($99/year), create provisioning profiles in the iOS Dev Center, and import them into AppBuilder. Unfortunately AppBuilder (or any other service) can’t remove any of these requirements as Apple provides zero APIs for this sort of thing. AppBuilder does provide comprehensive documentation to walk you through the process though.

In practice you’ll likely want to use the appbuilder deploy command, as it does a build and then automatically installs the app on a USB-connected iOS or Android device (appbuilder deploy ios and appbuilder deploy android, respectively). In the gif below I deploy the grocery list app to my iOS and Android devices. (Note that I artificially sped up this gif to avoid the wait during the builds. Builds generally take ~20–30 seconds.)

deploy

Even though your app is now a native app, you don’t have to give up the development conveniences AppBuilder provides. Want to see your changes reflected live? No worries, you can still use LiveSync.

$ appbuilder livesync ios --watch
$ appbuilder livesync android --watch

Need to debug your code? No worries, now that you have a true native app, you can use the browser’s native remote debugging tools. Here I inspect the Ionic header using the Chrome Dev Tools and Safari Web Inspector.

remote-debugging

For details on how to setup this remote debugging workflow check out our guide to remote debugging on iOS, Android, and Windows Phone.

Having a true native app lets you do one other important thing for hybrid development: add third-party Cordova plugins.

Integrating third-party Cordova plugins

At its core, Cordova is a series of conventions used to make communication between native APIs and a web view possible; therefore every native API is available to a Cordova-based app, but you need a plugin to access those APIs. The Cordova team provides ~15 of these plugins as part of the core library, but the community can create and publish plugins as well.

To find third-party plugins you can look through the Cordova Plugins Registry, or you can check out the Verified Plugins Marketplace, which is a curated set of plugins maintained by Telerik.

To show how all this works, let’s suppose you want to add sharing functionality to your grocery list app. As with the confirmation dialog, you could create a JavaScript-based sharing widget, but you can make the app feel more native using platform’s native control. It just so happens that the Verified Plugins Marketplace has a SocialSharing Cordova plugin to make using those controls simple.

With the AppBuilder CLI you install Cordova plugins using the plugin fetch command. So to install the SocialShare plugin you use the following:

$ appbuilder plugin fetch https://github.com/Telerik-Verified-Plugins/SocialSharing

From there, all you need to do is deploy the app (appbuilder deploy ios or appbuilder deploy android) and use the plugin’s documented API. The SocialSharing plugin exposes a number of methods, with several focusing on specific services: Twitter, Facebook, SMS, email, and so forth. For this article, we’ll stick with the plugin’s base window.plugins.socialsharing.share() method.

Start by adding a Share button to your header bar, so that it looks like this:

<ion-header-bar class="bar-positive">
    <h1 class="title">Grocery List</h1>
    <div class="buttons">
        <button class="button" ng-click="onShare()">Share</button>
    </div>
</ion-header-bar>

Then add the onShare() method that the delete button references:

$scope.onShare = function() {
    window.plugins.socialsharing.share(
        $scope.groceries.join( ", " ) );
};

That’s all there is to it! With a single line of code you can share your grocery list using the services your device natively provides. In the gif below I play around with sharing my groceries via email, SMS, and Twitter:

sharing

What Else?

Those are the highlights, but AppBuilder offers so much more I have to mention a few last things.

  • A UI for managing app icons so you don’t have to worry about crazy naming conventions? Check.

icons

  • A dedicated UI for toggling app permissions (which also has a clear description of what each permission is)? Check.

permissions

  • A clean UI for toggling Cordova plugins? Check.

cordova-plugins

documentation

Alright I’ll stop now. But seriously, if you’re an Ionic user you owe it to yourself to check AppBuilder out. Ionic helps you build beautiful UIs, but AppBuilder helps you turn that UI into real apps. AppBuilder is a paid product, but everyone gets a completely free 30-day trial, so you can give it a go and see what you think. We’d love to hear your feedback.

Header image courtesy of The359

Comments

  • Tom Bohon

    Great article, TJ … clear and concise. After almost 50 years of software development I’m just now getting into the Android mobile platform and this article clarified several things for me. Thanks!

  • Pingback: Kendo UI Integration with AngularJS – Webinar Resources | telerik helper()

  • Pingback: On Our Radar This Week: Apple, APIs and Web Apps()

  • Pingback: Starting Hybrid App Development with the AppBuilder CLI -Telerik Developer Network()

  • Great article. Easy to follow and to reproduce. I tried the browser IDE and I am having difficulties installing the socialsharing plugin. I right click my project, go to the verified marketplace, install the plugin (got succes message), but no plugin visible in my project. Also the code won’t trigger the sharing feature. So I am still wondering what I am doing wrong. Anyway, keep up the good work!

  • TJ, one question. When I try to add the navigator.notification.alert or confirm to a function inside my controller it shows an error in the console. On the device it doesn’t work either. The error is: TypeError: Cannot read property ‘confirm’ of undefined in ionic.bundle.js. Any tips more than appreciated.. 🙂

  • TJ, as soon as I add the cordova.js file to my app, the header (ion-nav-bar) is expanding one extra line as soon as the app starts. When I remove the cordova.js reference, the header does not expand and shows just one line. The same seems to appear in your screenshots. Any thoughts why this is happening?

  • surfyogi

    I’ve been using AppBuilder for a day, and really like it. I’d be very interested to know a few things as you see it:
    1) Ionic with AppBuilder – not exactly what Telerik intends to point users to, rather than kendo, but as soon as I saw the entire app suite, I understood I could use Ionic rather than Kendo if I want to (and avoid some lock-in, and enjoy a bigger community).

    2) I guess I give up on the PageBuilder (whatever it’s called, GUI IDE) with Ionic? I’d really rather not, so it would be pretty cool if you guys would support Ionic dev route with the builder IDE.. and Bootstrap UI, as well as any other I might care to register (Wijmo? 😉

    3) So we rearrange and become a mobile first society. I still have a web-app to support for my laptop users, can Ionic support desktop using some kind of link from @media queries to JS (Angular, Ionic), so that I can dynamically switch out to full JS widgets and browser services (geolocation) for a non-compiled, non-Cordova version? Any examples of a common code base still used for desktop web app?

    Very impressive stuff and thanks for a great article, I’m feeling a little late to the party.

  • Hey TJ, nice article. Thanks.

    QQ: How is appbuilder cli different from ionic cli, while building ionic apps?