Sample Force.com Mobile Application with Ionic and AngularJS

In my previous post, I wrote about Ionic, a new UI framework that’s built on top of AngularJS and that provides mobile-optimized UI components to build high-performance hybrid applications that look and feel native. I also shared an employee directory sample application built with Ionic and AngularJS.

In this post, I’ll share the same application connecting to the salesforce.com platform using the Force.com Mobile SDK. After authenticating with OAuth, the user can search for contacts by name, and then call, text, or email the selected contact.

Source Code

The source code for this sample application is available in this repository on GitHub.

Running the App

Follow the steps below to run the sample application (as a hybrid/Cordova app) in the iOS emulator or on an iOS device. Instructions to create a project using the Mobile SDK for Android are available here.

1. Make sure Node.js is installed on your system. If it’s not, you can install it from here.
2. Install the Force.com Mobile SDK for the platform of your choice (Android instructions are available here):

   sudo npm install -g forceios
   

3. Create a new application

   forceios create

   Answer the prompts as follows (adjust the company id and organization name as needed):

   Enter your application type (native, hybrid_remote, or hybrid_local): hybrid_local
   Enter your application name: force-contacts-angular-ionic
   Enter the output directory for your app (defaults to the current directory): 
   Enter your company identifier (com.mycompany): org.coenraets
   Enter your organization name (Acme, Inc.): Coenraets, Inc.
   Enter your Connected App ID (defaults to the sample app’s ID): 
   Enter your Connected App Callback URI (defaults to the sample app’s URI): 
   

   · You can also provide these values as command line parameters when invoking forceios create. Type forceios on the command line and press return for a list of options.
   · For a real life application, provide a specific Connected App ID and Callback URI. Instructions for creating a connected app are available here or here.
4. Delete the force-contacts-angular-ionic/www folder in the generated project folder.
5. Click here to download the source code for the sample application, then unzip the file anywhere on your file system.
6. Copy the force-contacts-angular-ionic/www folder from the unzipped file to the force-contacts-angular-ionic folder in your project folder.
7. Open force-contacts-angular-ionic.xcodeproj in Xcode and run the application in the emulator, or on your device.
   To run the application on your device, you need an Apple developer certificate and an application provisioning profile.
   

Code Highlights

The force.com integration is encapsulated in the “services” module (www/js/services.js). The module defines two services: OAuthService and ContactService. Here is a quick look at ContactService.

angular.module('contactmgr.services', [])

    .factory('ContactService', function($q, OAuthService) {

        function query(queryStr) {
            var deferred = $q.defer();
            OAuthService.getClient().query(queryStr,
                function(response) {
                    deferred.resolve(response.records);
                },
                function(error) {
                    deferred.fail(error);
                });
            return deferred.promise;
        }

        return {
            findAll: function() {
                return query('SELECT Id, Name, Title FROM contact LIMIT 50');
            },

            findByName: function(searchKey) {
                return query('SELECT Id, Name, Title FROM contact WHERE name LIKE \'%' + searchKey + '%\' LIMIT 50');
            },

            findById: function(contactId) {
                var deferred = $q.defer();
                OAuthService.getClient().retrieve('Contact', contactId, ['Id', 'Name', 'Title', 'Department', 'Phone', 'MobilePhone', 'Email'],
                    function(contact) {
                        deferred.resolve(contact);
                    },
                    function(error) {
                        deferred.fail(error);
                    });
                return deferred.promise;
            }

        }
    });

This pluggable architecture makes it easy to replace the production implementation connecting to force.com with another implementation, for example a test implementation using in-memory/mock data. The employee directory application mentioned above provides an example of an in-memory data service (see the code here).

Wrapping Up

The Ionic/AngularJS combination provides a solid foundation for developing modern mobile applications that are both well architected and native-looking. If that sounds interesting, I hope this sample application helps you get started quickly. Give it a try. I’m looking forward to your feedback.

Resources

Ionic Framework
AngularJS Framework
Getting started with the Force.com Mobile SDK for iOS
Getting started with the Force.com Mobile SDK for Android