Home

Awesome

ForceNG

AngularJS Service for using the Salesforce REST APIs

ForceNG is a micro-library that makes it easy to use the Salesforce REST APIs in AngularJS applications. ForceNG allows you to easily login into Salesforce using OAuth, and to manipulate your Salesforce data using a simple API.

ForceNG is similar to ForceTK, but has no jQuery dependency, is implemented as an AngularJS service, and is using promises instead of callback functions.

The main target for ForceNG are applications running on your own server (Heroku or elsewhere) and Cordova/Mobile SDK apps.

Browser and Cordova without Code Changes

If you develop a hybrid application using the Mobile SDK, you often switch back and forth between running the app in the browser and on device: Developing in the browser is generally faster and easier to debug, but you still need to test device-specific features and check that everything runs as expected on the target platforms. The problem is that the configuration of OAuth and REST is different when running in the browser and on device. Here is a summary of the key differences:

<table> <tr><td></td><td><strong>Browser</strong></td><td><strong>Mobile SDK</strong></td></tr> <tr><td>Requires Proxy</td><td>Yes</td><td>No</td></tr> <tr><td>OAuth</td><td>Window Popup</td><td>OAuth Plugin</td></tr> </table>

ForceNG abstracts these differences and allows you to run your app in the browser and on device without code or configuration changes.

Key Characteristics

Quick Start

To create and run a minimalistic sample app using ForceNG:

  1. Create a directory anywhere on your file system, copy forceng.js in that directory, and create a file named index.html implemented as follows:

    <html>
<body ng-app="miniApp">

<ul ng-controller="ContactListCtrl">
    <li ng-repeat="contact in contacts" href="#">{{contact.Name}}</li>
</ul>

<script src="cordova.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.14/angular.min.js"></script>
<script src="forceng.js"></script>

<script>
    angular.module('miniApp', ["forceng"])

        .controller('ContactListCtrl', function ($scope, force) {
            force.login().then(function () {
                force.query('select id, name from contact limit 50').then(
                    function (contacts) {
                        $scope.contacts = contacts.records;
                        console.log($scope.contacts);
                    });
            });
        });

</script>
</body>
</html>

    That's it! This is all you need to authenticate with OAuth, retrieve a list of contacts from Salesforce, and display that list in HTML.

    The <script src="cordova.js"></script> line is there to support running the app in Cordova. Note that the cordova.js file does not have to be present in your directory: it is automatically injected by the Cordova build process. If you know you will never run your app in Cordova, feel free to remove that line.

  2. Install force-server

    Because of the browser's cross-origin restrictions, your JavaScript application hosted on your own server (or localhost) will not be able to make API calls directly to the *.salesforce.com domain. The solution is to proxy your API calls through your own server. You can use your own proxy server, but ForceNG is tightly integrated with ForceServer, a simple development server for Force.com. To install ForceServer, make sure Node.js is installed on your system, open a command prompt and execute the following command:

    npm install -g force-server

    or (Unix-based systems)

    sudo npm install -g force-server

  3. Run the application.

    Open a command prompt, navigate to your sample app directory and type the following command:

    force-server

    This starts the ForceServer server on port 8200 and loads your sample app in your default browser. After authenticating against your developer org, you should see a list of contacts.

Starting in the Spring 15 release, some Salesforce REST APIs (like Chatter and sobjects) support CORS. To allow an app to make direct REST calls against your org, register the app domain in Setup: Administer > Security Controls > CORS.

Running in Cordova with the Mobile SDK

To run the same application in Cordova:

  1. Install Cordova:

    npm install -g cordova

    On a Mac, you may have to use sudo:

    sudo npm install -g cordova

  2. Create a new application:

    cordova create contactforce com.samples.contactforce contactforce

  3. Navigate (cd) to the project directory

    cd contactforce

  4. Add the Salesforce Mobile SDK plugin:

    cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin

  5. Delete the contents of the contactforce/www directory

  6. Copy forceng.js and the index.html file created above in the contactforce/www directory

  7. Create a file named bootconfig.json (the Salesforce Mobile SDK config file) in the contactforce/www directory and implement it as follows:

    {
  "remoteAccessConsumerKey": "3MVG9Iu66FKeHhINkB1l7xt7kR8czFcCTUhgoA8Ol2Ltf1eYHOU4SqQRSEitYFDUpqRWcoQ2.dBv_a1Dyu5xa",
  "oauthRedirectURI": "testsfdc:///mobilesdk/detect/oauth/done",
  "oauthScopes": [
    "web",
    "api"
  ],
  "isLocal": true,
  "startPage": "index.html",
  "errorPage": "error.html",
  "shouldAuthenticate": true,
  "attemptOfflineLoad": false
}

    For a production application, you should create a Connected App in Salesforce and provide your own Connected App ID and Callback URI.

  8. Add a platform. For example, to add iOS:

    cordova platform add ios

  9. Build the project:

    cordova build ios

Run the project. For example, for iOS, open the project (platforms/ios/contactforce.xcodeproj) in Xcode and run it in the emulator or on your iOS device. After authenticating against your developer org, you should see a list of contacts.

Note that you didn't change any code to run the app in Cordova. When running in Cordova, ForceNG automatically uses the Salesforce Mobile SDK OAuth plugin, and invokes REST services without using a proxy because the webview used in Cordova is not subject to the same cross domain policy restrictions.

Ionic Salesforce Template

Ionic is an open source SDK for developing hybrid mobile apps on top of AngularJS. The Ionic Salesforce Template is a starter application for building Ionic apps on top of the Salesforce platform. The template installs a starter application that uses ForceNG to authenticate and access the Salesforce REST APIs.

To create an application using the Ionic Salesforce Template:

  1. Install Cordova and Ionic:

    $ npm install -g ionic cordova

    On a Mac, you may have to use sudo:

    $ sudo npm install -g ionic cordova

  2. Create the app:

    $ ionic start myApp salesforce

  3. To run the app in the browser:

    cd myApp/www
force-server

  4. To run the app on device, cd back to the project root directory and execute the following command:

    ionic build ios

  5. Open the project (platforms/ios/myApp.xcodeproj) in Xcode and run it in the emulator or on your iOS device.

Other Sample

Using ForceNG in Visualforce Pages

Even though you should consider Visualforce Remoting or Remote Objects to avoid the governor limits related to the REST APIs, you can run ForceNG in Visualforce pages. To run a Visualforce page version of the sample above, upload forceng.js as a static resource and create a Visualforce page defined as follows:

<apex:page>
    
    <body ng-app="miniApp">
    
    <ul ng-controller="ContactListCtrl">
        <li ng-repeat="contact in contacts" href="#">{{contact.Name}}</li>
    </ul>
    
    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.14/angular.min.js"></script>
    <script src="{!$Resource.forceng}"></script>
    
    <script>
        // Keep this in the VF page to capture the Session Id and store it in an Angular Constant
        angular.module('config', [])
        	.constant('SESSION_ID', '{!$Api.Session_ID}');
	</script>    
        
	<script>
        // This is typically in a separate file like app.js
        angular.module('miniApp', ['forceng', 'config'])

            .controller('ContactListCtrl', function ($scope, force, SESSION_ID) {
                force.init({accessToken: SESSION_ID});
                force.query('select id, name from contact limit 50').then(
                    function (contacts) {
                        $scope.contacts = contacts.records;
                        console.log($scope.contacts);
                    });
            });
    </script>

    </body>

</apex:page>

Notice that in this case, you don't have to login: you just initialize ForceNG with the existing session id.

API Reference

init()

Used to initialize ForceNG with non-default parameters. ForceNG is built to work out of the box with sensible defaults. You only need to invoke force.init() if you want to override these defaults:

Parameters:

Use the following init parameters, if you don't need to authenticate the user because you already have an authenticated token. For example, if you are running the app from a Visualforce page. accessToken is the only required parameter in that scenario.

Example:

force.init({
    appId: '3MVG9fMtCkV6eLheIEZplMqWfnGlf3Y.BcWdOf1qytXo9zxgbsrUbS.ExHTgUPJeb3jZeT8NYhc.hMyznKU92',
    apiVersion: 'v33.0',
    loginURL: 'https://login.salesforce.com',
    oauthRedirectURL: 'http://localhost:8200/oauthcallback.html',
    proxyURL: 'http://localhost:8200'
});

query()

Used to execute a SOQL statement

Example:

force.query("SELECT id, name FROM contact").then(
    function(result) {
        console.log(result.records);
    ), function(error) {
        console.log(error);
    });

create()

Used to create a record for a Salesforce object

Example:

force.create('contact', {FirstName: "Lisa", LastName: "Jones"}).then(
    function(response) {
        console.log(response);
    },
    function(error) {
        console.log(error);
    });

update()

Used to update a record

Example:

force.update('contact', {Id: "0031a000001x7DOAAY", FirstName: "Emma", LastName: "Wong"}).then(
    function(response) {
        console.log(response);
    },
    function(error) {
        console.log(error);
    });

del()

Used to delete a record

Example:

force.del('contact', "0031a000001x7DOAAY").then(
    function(response) {
        console.log(response);
    },
    function(error) {
        console.log(error);
    });

upsert()

Used to upsert a record

Example:

force.query("SELECT id, name FROM contact").then(
    function(result) {
    ),
    function(error) {
    });

retrieve()

Used to retrieve a single record

Example:

force.retrieve('contact', id, null).then(
    function(contact) {
        console.log(contact);
    },
    function(error) {
        console.log(error);
    });

apexrest()

Used to invoke a custom REST service endpoint implemented by your own Apex class.

Example:

force.apexrest("contacts").then(
    function(result) {
        console.log(result)
    ),
    function(error) {
        console.log(error);
    });

request()

The core method to invoke a REST services. Other functions (query, create, update, del, upsert, apexrest) are just convenience functions invoking request() behind the scenes. You can use request() directly to invoke other REST services that are not directly exposed through a convenience function.

Example:

force.request({path: "/services/data"}).then(
    function(result) {
        console.log(result)
    ),
    function(error) {
        console.log(error);
    });

Parameters:

isAuthenticated()

Used to figure out if the user is authenticated, in other words ForceNG has an authenticated access token.

Example:

alert(force.isLoggedIn());

getUserId()

Used to get the authenticated user's id

Example:

alert("The current user is: " + force.getUserId());

discardToken()

Used to discard the authentication token.

Example:

force.discardToken();

chatter()

A convenience function to use the Chatter API

Example:

force.chatter({path: "/users/me"}).then(
    function(result) {
        console.log(result)
    ),
    function(error) {
        console.log(error);
    });

Parameters:

JavaScript Version

A plain JavaScript version (ForceJS) is available here.

Other Libraries

ForceNG was built based on the following requirements:

Depending on your own requirements, you should also consider the following libraries: