Using Spanning Backup for Salesforce as a real-world example, we'll walk you through the steps to translate your Canvas app into a mobile app that can be used on Salesforce1. We'll explain the steps necessary in Salesforce, the technologies and tools we used, the challenges we encountered and how we overcame them. This is a terrific resource for anyone looking to get started with Salesforce1. If you'd like to download the full developer guide, you can get it here: http://bit.ly/SF1devguide.
Developer Guide: Turn Your Force.com Canvas App Into a Salesforce1 App
1. Surface Your Existing Force.com Canvas App in
Salesforce1
Patricia Cifra
Senior Software Eng.
@pncifra
Gordon Bockus
Senior Software Eng.
@gordonk66
2. Overview
• What is a Canvas App?
• What is a Salesforce1 App?
• Configuration Changes
• Application Changes
• Tools
• Challenges
3. What is a Canvas app?
• Web application embedded in the Salesforce platform via an iframe.
• Has several advantages over a standalone third-party Salesforce offering
• When launched, app is provided with signed request. This signed request gives the app the ability
to identify the user/organization that is accessing the it and an authentication token that can be
used to acquire Salesforce data via the Force.com rest API.
• Also provides mechanisms for the application to resize its containing iframe to fit into the view
where it is embedded.
• Can be inserted in various locations throughout the Salesforce CRM:
• Standalone page with its own tab
• Embedded in any of the standard objects like Accounts, Leads, Contacts, etc.
• Can also be linked to a Chatter post
• Allows you to have a single app that adapts to where it is being displayed
7. What is a Salesforce1 app?
• New Mobile platform for Salesforce
• Built around Salesforce’s API feeds
• Platform that is mobile-ready and more accessible to customers
• Accessible via web/browser or native web
• Mobile platform introduced at Dreamforce last year
8. Technology Stack
• AngularJS: Open-source web application framework maintained by google.
Used for building SPAs (Single page apps)
• Twitter Bootstrap 3: Front-end framework built by Twitter that provides grids,
components, javascript plugins, typography, form controls
• Sass: CSS preprocessor that provides tools to better organize and maintain
your CSS
• Node: Cross platform runtime environment for server-side and networking
applications. runs our server side application which is written in javascript
9. Tools and Frameworks for Mobile
• Twitter Bootstrap 3
• Multi-device support
• Mobile first and always responsive
• Preprocessors
• Cross browser
• Mobile detection in Angular
14. Web Application Changes
• Detecting Mobile:
• Width
• http://detectmobilebrowsers.com
• After Mobile is Detected:
• Add CSS class to main container
• Direct application to load mobile view
28. Development - Native
• Deploy to a public webserver
• Install Canvas app in test domain
• Test on devices
• Test web version!
29. Challenges
• Resolved
• IOS: Bootstrap responsive layout not adhering to width of device
• Android: SVG images do not scale
• Open
• Android: Scrolling broken at times
• SF1: Long Visualforce pages jump to top
• Fixed header
30. Visit us at booth #N2236
Download the Developer Guide:
httttp::////biitt..lly//SF1devguiide
Notes de l'éditeur
To to make the Canvas app show up as an option in the Salesforce1 menu, you will need to enable mobile navigation. This is done by navigating to the Mobile Administration menu then selecting the Mobile Navigation link. The Visualforce page you just enabled for mobile should be listed in the Available section. Select it and click the right arrow to add it to the Selected list.
Your Canvas app will need to be embedded in a Visualforce page to be available in Salesforce1. To make it available, you edit the Visualforce page by navigating to the Develop menu, then select Pages, and Edit the page associated with your Canvas app. Then check the option ‘Available for Salesforce Mobile apps.’ If you weren’t previously using a Visualforce page to provide your Canvas app, you will need to ensure that the Visualforce page location is enabled. This can be verified by editing your application in the Apps view of the CRM.
This step is optional, but adds some value to having an application in Salesforce1, so you might want to include it as an option in your install instructions for your application. It will result in a web-based version of Salesforce1 loading when users from the organization log in to Salesforce from a mobile browser. The final thing you should consider adding is a custom icon for your application. The icon is much more prominent in Salesforce1 then the CRM and can make a lasting impression on users interacting with your app. Your icon is provided via an https URL. This value can be set from your Connected App configuration page. OK that’s it - now your Canvas app is available from Salesforce1.
I’m going to assume that you have a single application that is going to adjust to the location where it’s being displayed since that’s one of the advantages of developing for the Canvas platform. If you decide to have separate applications for web and mobile, then some of these steps can be excluded. To determine if the app is being viewed on mobile, the simplest approach is to examine the width of the Canvas app container. The problem with doing so is that if you have a responsive application, then it will render taking up as much space as possible and there is nothing to prevent it from overrunning the width of the device. With how Canvas apps are displayed in Salesforce1, there are several layers of iframe between your application and the parent container that is sized to fit the mobile device display. This being the case there is no way to get an accurate parent width from the Canvas API as of the Spring 14 release of SF. <NOTE There have been improvements to how the Canvas app is loaded in the SUMMER 14 release.> As a workaround, we used the information and code found on the detectmobilebrowsers.com website. It’s just a short JavaScript function that can be executed to determine if the current browser is on a mobile device.
You will need to set your Canvas app to autosize true in order to best fit the different sizes of display available on mobile. That way the app will take all available content space when loaded in Salesforce1. You don’t want to have a scrollable area smaller than the content view in Salesforce1. This function is specific to our Angular application, so yours might look slightly different. The important thing to note here is the call the the Canvas API to turn on the autogrow feature. Note that userInfo.client is the client property provided to us by Salesforce in the signed request that is posted to the app on load.
When loading the application we use JavaScript to evaluate if the app is being loaded on a mobile device. If so, we attach the sbsf-sf1 class to the body tag. Using this tag, we are able to set the width for the mobile site.
The sbsf-sf1 class is the class that we added to our top level dom object. For mobile, we will be using em’s to scale appropriately for different form factor so we set a base font-size. We use Sass in our application if you were wondering about this odd looking CSS. Even if you aren’t familiar with Sass, you can glean that eventually CSS is applied to the page. We want to set the width to 100% so that it always fills all available space. Note that our web application has a static width of 1200 pixels.
The main objective is to ensure your app will always fill the horizontal space and scroll up and down.
Here are a few additional css rules you should consider for you application. This was taken from the Canvas developer guide. The min-height is good so that your application is always visible regardless of how small the display may be. Setting the overflow will ensure that your app is scrollable and won’t clip any content. The width of 100% ensure our fill horizontally requirement. The webkit specific
For our main desktop app we have templates and controllers for our specific views. - move this up to the mobile template slides
In our mobile app we create new templates for mobile specific views we are able to reuse our controllers to provide support for the template data.
We had a mobile.scss file here and rules were created that only apply to mobile. For example, we used em and percentages instead of static px.
With our desktop app we have templates for our views that we load. For the mobile app we replaced the templates with mobile templates. Mobile templates were lighter-weight and used responsive classes from Twitter Bootstrap. The top view is our template for the main app for mobile and the bottom is our template for the full desktop app.
If you load your Salesforce instance and alter the URL to one/one.app, it will load the Salesforce1 app in the browser. That coupled with a feature in the Chrome developer tools that allows you to emulate many mobile devices gives you a good place to develop your application. Be aware that this is the land of milk and honey: everything will work and behave perfectly, so it is a good place to do initial development and validation, but you must also test your application on the devices where your users will be using it.
The easiest way to test natively on iOS is to use the iOS Simulator. You must have a Mac in order to do this. To launch the simulator you must install Xcode and launch the simulator from there. Then you will be able to load your application through the Safari browser on the simulator. This gives you a nearly identical experience to running through the Salesforce1 app in that on iOS, your application is running on a webview that is very similar to the native Safari experience. Performance and behavior were very similar between the emulator and real Salesforce1 application. When running on the emulator, you have the ability through the desktop Safari to launch a Web Inspector that is connected to the Salesforce1 app running on the emulator. This is very helpful in debugging styling issues that are iOS-specific.
Testing on Android was much more challenging. If you download the Android SDK, it comes with an emulator, but is painfully slow, and out of the box there is no way to install the Salesforce1 application. The alternative we found was an emulator that is produced by a company called Genymotion. It is already configured so it performs much better than the default emulator. With some googling, you can also easily get the Google Play store installed so you can actually test your application in the Salesforce1 native app. We never found a good way to debug on the emulator, so were forced into the guess-and-check method of debugging. Because your Canvas application is a website, you have to make the emulator able to find your developer box in order to load the Canvas application. We did this by adding the hostname to our local machines hosts file and configuring a static IP for that host on the router.
Finally you must test your application on devices. Sadly they are never exactly like even the best of emulators. In order to do this, we created a staging environment where we had our web application deployed to a publicly-available server. Then in a developer Salesforce account, install your Canvas application and have it use the server where your web application is hosted as the Canvas app URL. This enables you to install the Salesforce1 application on whatever devices you have available and log into the test account. My suggestion is to hold your breath, close your eyes, open the application, and hope for the best.
We had a few challenges; in other words, OS specific bugs that we encountered. We have a few places in our application where a panel scrolls horizontally to display more data, and with the default Bootstrap3 setup, the row was failing to limit the size of the container. We got around this by removing the Bootstrap3 CSS classes and writing our own custom layout. An odd Android issue was that using an svg image as a background image would not scale properly. We had to go back and wrap those images in divs that are sized to fit the image.
In Android, we had an issue where a long page will only scroll down about 50%. There is an issue with the Salesforce1 application that we ran into. If your page gets really tall, it randomly jumps back to the top of the page. We are following that open issue on the Salesforce forums. The suggested workaround was to not make your Visualforce pages too tall which wasn’t an option for us. Finally, our original design was to have a fixed header inside the application and scroll the body of our app instead of the Salesforce1 container. We found that this could be accomplished if we added a scroll listener to the Canvas app then adjusted the size of the body after the user had trigger a scroll event. However, this wasn’t a great user experience in that it required the user to always scroll after launch, so we worked with our design team to make the header not fixed.
The takeaways from this is you must test across the different platforms.