Managing Navigation

Navigation with the sforce.one Object

The Salesforce1 Platform includes an event mechanism for navigation. This is exposed in Visualforce as a JavaScript object called sforce.one. It’s available in any page that appears in Salesforce1.

The sforce.one object provides the following functions. Reference the function using dotted notation from the sforce.one object. For example: sforce.one.navigateToSObject(recordId, view).

How sforce.one Handles API Versions

The sforce.one object is frequently improved in new releases of the Salesforce1 Platform. To maintain backward compatibility, sforce.one provides version-specific behavior, and you can use a specific version of sforce.one in your apps.

By default, sforce.one uses the same version as the API version of the requested Visualforce page. For example, if a Visualforce page has an API version of 30.0, JavaScript on that page that uses sforce.one by default uses the API version 30.0 of sforce.one.

This means that when a Visualforce page is updated to a new API version, the page automatically uses the updated version of sforce.one. In the preceding example, if that Visualforce page is updated to API version 31.0, app functionality that uses sforce.one uses the API version 31.0 of sforce.one.

Using a Specific Version of sforce.one

To use a specific version of sforce.one, use the sforce.one.getVersion() function and provide it with the API version and a callback function that needs to use a specific version of sforce.one. The appropriate versions of sforce.one are automatically loaded by this call.

1sforce.one.getVersion(versionString, callbackFunction);

versionString is the API version that your application requires. It’s always two digits, a period, and one digit, such as “30.0”. Calls with invalid version strings fail silently.

callbackFunction is a JavaScript function that uses a specific version of sforce.one. sforce.one.getVersion() operates asynchronously, and your callback function is called when it finishes loading the requested version of sforce.one. Your callback function receives a single parameter, an sforce.one object for the specified API version. Use the object passed in instead of the global sforce.one to make calls to sforce.one that conform to the API version that your app requires.

Examples of Using a Specific Version of sforce.one

1<input type="button" value="Create Account" onclick="btnCreateAccount()" id="btnCreateAcct"/>

Defaulting to the Visualforce Page’s API Version

1<script>
2    function MyApp() {
3        this.createAccount = function() {
4            sforce.one.navigateToURL("/001/e");
5        };
6    } 
7
8    var app = new MyApp();
9
10    function btnCreateAccount() {
11        app.createAccount();
12    }
13</script>

App functionality is created in a MyApp object, and then an event handling function calls the app function when that event, a button click, occurs. Separating application functionality from application event handling is a best practice, and it sets you up for using version-specific versions of sforce.one.

Using a Specific sforce.one API Version (Simple)

1<script>
2    function MyApp(sfone) {
3        this.createAccount = function() {
4            sfone.navigateToURL("/001/e");
5        };
6    } 
7        
8    var app30 = null;
9
10    function btnCreateAccount() {
11        // Create our app object if not already defined
12        if(!app30) {
13            // Create app object with versioned sforce.one
14            sforce.one.getVersion("30.0", function(sfoneV30) {
15                app30 = new MyApp(sfoneV30);
16                app30.createAccount();
17            });
18            return;
19        }
20        app30.createAccount();        
21    }
22</script>

In the preceding example, the event-handling function is expanded from the first example to include the creation of a version-specific instance of sforce.one. If your app needs to mix multiple versions, you can create multiple MyApp instances with appropriate versions and names. More than one or two, though, are cumbersome to manage. We recommend the next approach instead.

Using a Specific sforce.one API Version (Best)

1<script>
2    function MyApp(sfone) {
3        this.createAccount = function() {
4            sfone.navigateToURL("/001/e");
5        };
6    } 
7        
8    var app30 = null;
9
10    // Initialize app: get versioned API, wire up clicks
11    sforce.one.getVersion("30.0", function(sfoneV30) {
12        // Create app object with versioned sforce.one
13        app30 = new MyApp(sfoneV30);
14
15        // Wire up button event
16        var btn = document.getElementById("btnCreateAcct");
17        btn.onclick = btnCreateAccount;
18    });
19
20    // Events handling functions
21    // Can't be fired until app is defined
22    function btnCreateAccount() {
23        app30.createAccount();
24    }
25</script>

In this sample the app initialization is separated only by white space and comments, but you can separate it into functions for better encapsulation.

Using a Specific sforce.one API Version (Synchronous)

1<script src="/sforce/one/30.0/api.js"></script>
2<script>
3    function MyApp(sfone) {
4        this.createAccount = function() {
5            sfone.navigateToURL("/001/e");
6        };
7    } 
8        
9    var app = null;
10
11    sforce.one.getVersion("30.0", function(sfoneV30) {
12        app = new MyApp(sfoneV30);
13    });
14
15    // Events handling function
16    // Can't be fired until app is defined
17    function btnCreateAccount() {
18        app.createAccount();
19    }
20</script>

Although some situations require synchronous mode, the asynchronous version is preferred. If you forget to manually include the correct versions of the sforce.one library, your code will contain bugs that are difficult to diagnose.