How sforce.one Handles API Versions

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.