Salesforce1 Mobile App Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Managing Navigation

Salesforce1 manages navigation using events. The navigation event framework is made available as a JavaScript object that provides a number of utility functions that make creating programmatic navigation that “just works” a breeze. The advantage is a navigation experience that’s more natural for a mobile context. It also makes creating post-completion navigation, such as redirecting to an order page after the order is successfully submitted, easier for Salesforce1 developers.
In Salesforce1, programmatic navigation for Visualforce pages generally works something like this:
  1. A user invokes a Visualforce page, usually from the navigation menu, or from an action in the action bar.
  2. The Visualforce page loads and runs, including any custom controller or extension code called by the page.
  3. The user interacts with the page in some way: for example, to fill in some form values.
  4. The user submits the form, or performs some other action on the page that commits a change.
  5. Controller or extension code runs, saving the changes to Salesforce, and returning the results of the action.
  6. The Visualforce page, using JavaScript response handlers, receives the results of the action, and when successful, responds by redirecting the user to a new page that shows the results of their action.
This scenario is easily handled by the Salesforce1 navigation framework.

Another common use case is simply adding links or other user interface controls to a page, which move from that Visualforce page to another page in Salesforce1. This navigation is also easily managed by the Salesforce1 navigation framework.

In these cases, navigation is handled by a special utility JavaScript object, sforce.one. The sforce.one object is automatically added to all Visualforce pages when they run inside the Salesforce1 app. This object provides a number of functions that trigger navigation events when they run. To use these functions, you can call them directly from your page’s JavaScript code, or you can attach calls as click handlers to elements on the page.

Here’s a JavaScript function, from the FindNearbyWarehousesPage page introduced in Extending Salesforce1 with Visualforce Pages, which creates markers to add to a Google map.
1function setupMarker(){ 
2
3    // Use JavaScript nav function to determine if we are
4    // in Salesforce1 and set navigation link appropriately
5    var warehouseNavUrl = 
6        'sforce.one.navigateToSObject(\'' + warehouse.Id + '\')';
7
8    // Wrap the warehouse details with the link to 
9    // navigate to the warehouse details
10    var warehouseDetails = 
11        '<a href="javascript:' + warehouseNavUrl + '">' + 
12        warehouse.Name + '</a><br/>' + 
13        warehouse.Street_Address__c + '<br/>' + 
14        warehouse.City__c + '<br/>' + 
15        warehouse.Phone__c;
16   
17    // Create a panel that will appear when a marker is clicked
18    var infowindow = new google.maps.InfoWindow({ 
19        content: warehouseDetails
20    });
21   
22    // ...
23}
The very first line builds a string, warehouseNavUrl, that, when used as a JavaScript URL, navigates to the detail page for the warehouse. The link is created around the warehouse name, and appears in the information panel (put together in the warehouseDetails string) that appears when you click a marker. Clicking the warehouse name takes you to the detail page for that warehouse (the omitted part of the function code deals with the Google Maps API calls to create a marker and add it to the map).
If you have JavaScript code or HTML markup that runs inside of Salesforce1, keep these considerations in mind:
  • Don’t directly manipulate the browser URL using window.location.href. This doesn’t work well with the Salesforce1 navigation management system.
  • Don’t use target="_blank" in navigation URLs; you can’t open new windows inside Salesforce1.

Navigation Methods within the Force.com Canvas Framework

If you’re using Force.com Canvas, there’s a simpler way to control navigation around canvas apps and canvas personal apps in Salesforce1.

You can use Force.com methods to control navigation in Salesforce1. These methods within the Force.com Canvas framework are events that reside in the JavaScript library. When you call one of the navigation methods from your canvas code, you send an event into Salesforce1 that reads the payload and directs the user to the specified destination.

Reference the navigation method as an event variable, with name and payload. For example:

var event = {name:"s1.createRecord", payload: {entityName: "Account", recordTypeId: "00h300000001234"}};

For more information about using the new methods, see “Salesforce1 Navigation Methods for Use with Canvas Apps” in the Force.com Canvas Developer’s Guide.