Building Mobile Apps for with Ratchet 2.0

In my previous post, I shared a sample mobile application built with the freshly released Ratchet 2.0. Ratchet is a UI toolkit (mostly CSS) that provides skins and UI components for mobile applications built with web standards.

In this post, I’ll share a similar application for the platform. This sample application provides you with a quick access to your Salesforce Contacts on your mobile device. After authenticating with OAuth, you can search for contacts by name, and then view, edit, call, text, or email the selected contact. The application uses Ratchet for the User Interface, and the REST APIs to integrate with Salesforce.

Try It Here

You can experience the application in the phone “simulator” below (type a few characters in the search box), or click here to run the app in its own browser window.

The version above uses an in-memory dataservice (described below in “Code Highlights”) that makes it easy to experience the application without a Salesforce account, or to implement fine-grained unit tests.

Source Code

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

Running the Application on your Device

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.

You’ll need a account to run this application. If you don’t already have one, you can sign up for a free developer environment here.
  1. Make sure Node.js is installed on your system. If it’s not, you can install it from here.
  2. Install the 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-ratchet
    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-ratchet/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-ratchet/www folder from the unzipped file to the force-contacts-ratchet folder in your project folder.
  7. Open force-contacts-ratchet.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

Ratchet is mostly CSS and is framework-agnostic: you can use it with any MVC framework: AngularJS, Backbone.js, Ember, Knockout, etc. To keep this sample application generic, I didn’t use any specific MVC framework in this implementation of the app.

The integration is encapsulated in the data service module (www/js/contactservice-rest.js):

var services = (function() {

    function ContactService(forceClient) {

        function findAll(successHandler, errorHandler) {
            var soql = 'SELECT Id, FirstName, LastName, Title FROM contact LIMIT 50';
            forceClient.query(soql, function(data) {
            }, errorHandler);

        function findByName(searchKey, successHandler, errorHandler) {
            var soql = 'SELECT Id, FirstName, LastName, Title FROM contact WHERE name LIKE \'%' + searchKey + '%\' LIMIT 50';
            forceClient.query(soql, function(data) {
            }, errorHandler);

        function findById(contactId, successHandler, errorHandler) {
            var fieldList = ['Id', 'FirstName', 'LastName', 'Title', 'Department', 'Phone', 'MobilePhone', 'Email'];
            forceClient.retrieve('Contact', contactId, fieldList, successHandler, errorHandler);

        function save(original, changes, successHandler, errorHandler) {
            if (original) {
                forceClient.update('Contact', original.Id, changes, function(data) {
                    changes.Id = original.Id;
                }, errorHandler);
            } else {
                forceClient.create('Contact', changes, function(data) {
                    changes.Id = data.Id;
                }, errorHandler);

        return {
            findAll: findAll,
            findByName: findByName,
            findById: findById,
            save: save


    return {
        ContactService: ContactService


This pluggable architecture makes it easy to replace the production implementation of the data service connecting to Salesforce with another implementation. For example, a test implementation using in-memory/mock data is provided in contactservice-memory.js and is used in the “phone simulator” above.

Final Thoughts

Ionic is another UI toolkit with a lot of momentum in this space. Which UI toolkit should you choose? If you are using AngularJS, Ionic seems like an obvious choice right now: It is built on top of AngularJS and the combination provides a really solid foundation for developing modern mobile applications that are both well architected and native-looking. If you are using another framework or no MVC framework at all, Ratchet is a great, non-intrusive option to get you started.