Salesforce1 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 the publisher.
  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 all 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.
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 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).

navigateToSObject(recordId,view) Navigates to an sObject record, specified by recordId.

view is optional, and specifies the view within record home to select—chatter, related, or detail.
navigateToURL(url) Navigates to the specified URL.

Relative and absolute URLs are supported. Relative URLs retain navigation history, absolute URLs open a child browser window.
navigateToFeed(subjectId, type) Navigates to the specific feed, subjectId.

type is the expected feed type, for example NEWS.
navigateToFeedItemDetail(feedItemId) Navigates to the specific feed item, feedItemId.
navigateToRelatedList(relatedListId, parentRecordId) Navigates to the related list as specified by the relatedListId. The parentRecordId is the record of the parent object. For example, for a related list of Warehouses, the parentRecordId would be Warehouse__c.Id.
navigateToList(listViewId, listViewName, scope) Navigates to the list view as specified by the listViewId and listViewName.
createRecord(entityName, recordTypeId) Opens the page to create a new record for the specified entityName.

recordTypeId is optional, and if provided, specifies the record type for the created object.
editRecord(recordId) Opens the page to edit the record specified by recordId.
Keep the following in mind when using the sforce.one object:
  • Calls to sforce.one.navigateToURL may result in an “Unsupported Page” error if the URL references standard pages for objects or Chatter pages. To avoid this error, ensure that the URL begins with a backslash (/_ui instead of _ui).
  • The sforce.one.createRecord and sforce.one.editRecord methods don’t respect Visualforce overrides on these standard actions.