Start tracking your progress
Trailhead Home
Trailhead Home

Understand a Sample Hybrid App

Learning Objectives

After completing this unit, you’ll be able to:

  • Run the ContactExplorer sample hybrid app
  • Understand how the ContactExplorer app works
  • Use the Salesforce OAuth plugin to manage user authentication and session retention

Run the ContactExplorer App

Let’s look at the ContactExplorer sample app, which is included in Mobile SDK. ContactExplorer is a hybrid local app that demonstrates more functionality than the template app. You can do this exercise on Mac OS or Windows, but you can fully validate the iOS target only on a Mac.

Before starting this exercise, be sure that you have:
  • A directory to contain the SalesforceMobileSDK-Shared cloned repo—your root directory, or any other easily accessible location.
  • A directory for creating and developing Mobile SDK hybrid projects. Since Cordova projects can contain both iOS and Android targets, it’s a good idea to put them in a platform-neutral directory.

Source code for sample apps lives on GitHub, so let’s start by cloning the shared repository.

  1. Open a command prompt or Terminal window.
  2. Clone the shared repo:
    git clone https://github.com/forcedotcom/SalesforceMobileSDK-Shared
  3. cd to your app’s project directory. The force script prints the directory name to the screen when it has finished creating your project. For example: “Your application project is ready in <project directory name>.”
  4. Run forcehybrid create with the following values:
    Enter the target platform(s) separated by commas (ios, android): ios,android
    Enter your application type (hybrid_local, hybrid_remote): hybrid_local
    Enter your application name: contactsApp
    Enter the package name for your app (com.mycompany.myapp): com.salesforce.contactexplorer
    Enter your organization name (Acme, Inc.): AcmeApps.com
    Enter output directory for your app (leave empty for the current directory): <press RETURN>
  5. After forcehybrid finishes, run the following commands.
    cd contactsApp
    cordova plugin add cordova-plugin-contacts
    cordova plugin add cordova-plugin-statusbar
    cordova plugin remove com.salesforce
    cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin --force
    cp -RL <local path to SalesforceMobileSDK-Shared>/samples/contactexplorer/* www/
    cordova prepare
    Note

    Note

    Windows users: On Windows, substitute the copy command for the cp Unix command. Be aware, however, that files in the js and css subfolders of /samples/contactexplorer/ are aliases to source files on other paths. Make sure that you copy the source files themselves rather than their aliases. Here’s an example:

    cd contactsApp
    cordova plugin add cordova-plugin-contacts
    cordova plugin add cordova-plugin-statusbar
    cordova plugin remove com.salesforce
    cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin --force
    rem Make a path variable
    set SHAREDPATH=C:\SalesforceMobileSDK-Shared\
    md www
    cd www
    md css
    copy %SHAREDPATH%\samples\common\jquery.mobile-1.3.1.min.css css
    md js
    copy %SHAREDPATH%\test\MockCordova.js js
    copy %SHAREDPATH%\libs\cordova.force.js js
    copy %SHAREDPATH%\libs\force.js js
    copy %SHAREDPATH%\dependencies\jquery\jquery.min.js js
    copy %SHAREDPATH%\samples\common\jquery.mobile-1.3.1.min.js js
    cordova prepare

The forcedroid script and the ensuing commands create an iOS project and an Android project, both of which wrap the ContactExplorer sample app. Now we’re ready to run the app on one of these platforms. If you’re using an iOS device, you must configure a profile for the simulator, as described in the Xcode User Guide at developer.apple.com/library. Similarly, Android devices must be set up as described at developer.android.com/tools.

When you run the app, after an initial splash screen, you see the Salesforce login screen.

Mobile Login Screen

Log in with your Developer Edition org username and password. To allow the app to access your Salesforce data, tap Allow. Now that you’re in the app, you can retrieve lists of contacts and accounts. Tap Fetch SFDC contacts to retrieve Salesforce contact names or Fetch SFDC Accounts to retrieve account names from your DE organization.

Sample Hybrid App

With each tap, the app appends rows to an infinite list. Scroll down to see the full list.

Sample Hybrid Contacts

Let's take a closer look at how the app works.

Understanding the ContactExplorer App

Let's take a closer look at how the ContactExplorer app works. The two most interesting files are index.html and inline.js.

  1. In the contactsApp project, open the www/index.html file.
  2. Find “function onDeviceReady()”.

To initiate a user session with force.js, you call force.login(). After the user logs in to an app running in the container, the network plug-in refreshes tokens as necessary when the app tries to access Salesforce resources. The following code, adapted from the ContactExplorer sample, demonstrates a typical force.login() implementation.

When the device notifies that it’s ready, you call the force.login() method to post the login screen.

/* Do login */
force.login(
    function() {
        console.log("Auth succeeded"); 
        // Call your app’s entry point
        // ...
    },
    function(error) {
        console.log("Auth failed: " + error); 
    }
);

After completing the login process, the sample app displays index.html (located in the www folder). When the page has completed loading and the mobile framework is ready, the jQuery(document).ready() function calls regLinkClickHandlers(). This function (in inline.js) sets up click handlers for the various functions in the sample app. For example, the #link_fetch_sfdc_contacts handler runs a query using the force object.

$j('#link_fetch_sfdc_contacts').click(function() {
    logToConsole("link_fetch_sfdc_contacts clicked");
    force.query("SELECT Name FROM Contact", 
        onSuccessSfdcContacts, onErrorSfdc); 
});

The force object is set up during the initial OAuth 2.0 interaction, and gives access to the REST API in the context of the authenticated user. Here, we retrieve the names of all the contacts in the DE organization. onSuccessSfdcContacts() then renders the contacts as a list on the index.html page.

$j('#link_fetch_sfdc_accounts').click(function() {
    logToConsole("link_fetch_sfdc_accounts clicked");
    force.query("SELECT Name FROM Account", 
        onSuccessSfdcAccounts, onErrorSfdc); 
});

Similarly to the #link_fetch_sfdc_contacts handler, the #link_fetch_sfdc_accounts handler fetches Account records via the REST API. The #link_reset  and#link_logout handlers clear the displayed lists and log out the user, respectively.

Notice that the app can also retrieve contacts from the device—something that an equivalent web app would be unable to do. The following click handler retrieves device contact query by calling the Cordova contacts plug-in.

$j('#link_fetch_device_contacts').click(function() {
    logToConsole("link_fetch_device_contacts clicked");
    var contactOptionsType = cordova.require(
        "org.apache.cordova.contacts.ContactFindOptions");
    var options = new contactOptionsType();
    options.filter = ""; // empty search string returns all contacts
    options.multiple = true;
    var fields = ["name"];
    var contactsObj = cordova.require(
        "org.apache.cordova.contacts.contacts");
    contactsObj.find(fields, onSuccessDevice, 
        onErrorDevice, options);
    });
});

This handler calls find() on the org.apache.cordova.contacts.contacts object to retrieve the contact list from the device. The onSuccessDevice() function (not shown here) renders the contact list into the index.html page.

Get the complete ContactExplorer sample application here: https://github.com/forcedotcom/SalesforceMobileSDK-Shared/tree/master/samples/contactexplorer

The force.js Library

Near the top of the index.html file, the app loads the Mobile SDK JavaScript library:
<!-- include force.js for REST transaction support -->
<script src="js/force.js"></script>
This library contains the basic underlying JavaScript functionality for all Mobile SDK hybrid apps. It calls into native code and implements your token refreshes and low-level network calls. Other features covered by force.js are REST API wrapper functions and user agent construction.

When you load the force.js library, it creates a global force object. This object is the entry point to the library’s functionality. As mentioned previously, the salesforceSessionRefreshed function uses the force instance to make network calls such as force.query().

This overview has been brief but meaty. Other UI widgets in the ContactExplorer app behave similarly to the ones we’ve discussed. In your spare time, it’s a good idea to study the code in both index.html and inline.js to round out your understanding. In the meantime, we’re heading on to more in-depth discoveries on hybrid interactions with Salesforce. Excited? Of course you are!

retargeting