Salesforce Canvas LifeCycle Handler
Introduction
In this blog, I am going to explain how to use canvas lifecycle handler to send the context information to canvas app and add custom behavior when your app when it is rendered.To handler the canvas lifecycle you need to implement the CanvasLifecycleHandler interface. With lifecycle handler, you can
- Control what sections of the CanvasRequest Context data get sent to your apps such as Organization, User or record details.
- Retrieve application context data when the app is rendered and alter the behavior of your app accordingly.
- Modify some of the context data, such as the canvas app URL, custom parameters, or the list of object fields that are returned in the Record data when the app is rendered.
- Display proper error message back to Salesforce
Creating a CanvasLifecycleHandler
Crate an apex class by implementing Canvas.CanvasLifecycleHandler interface provides methods and callbacks for customizing app lifecycle behavior as shown below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
public class CanvasLifeCycle implements Canvas.CanvasLifecycleHandler { public Set<Canvas.ContextTypeEnum> excludeContextTypes(){ Set<Canvas.ContextTypeEnum> excluded = new Set<Canvas.ContextTypeEnum>(); excluded.add(Canvas.ContextTypeEnum.ORGANIZATION); excluded.add(Canvas.ContextTypeEnum.USER); excluded.add(Canvas.ContextTypeEnum.RECORD_DETAIL); return excluded; } public void onRender(Canvas.RenderContext renderContext) { Canvas.ApplicationContext app = renderContext.getApplicationContext(); Canvas.EnvironmentContext env = renderContext.getEnvironmentContext(); Double currentVersion = Double.valueOf(app.getVersion()); if (currentVersion <= 5){ throw new Canvas.CanvasRenderException('Error: Versions earlier than 5 are no longer supported.'); } app.setCanvasUrlPath('/alternatePath'); env.addEntityFields(new Set<String>{'Name','BillingAddress','YearStarted'}); Map<String, Object> previousParams = (Map<String, Object>) JSON.deserializeUntyped(env.getParametersAsJSON()); previousParams.put('newCustomParam','newValue'); env.setParametersAsJSON(JSON.serialize(previousParams)); } } |
Let’s understand the code now. The first method is used to filter CanvasRequest Context data that gets sent to your canvas app as shown below .with excludeContextTypes() types method you can specify what data you wanted to exclude from the canvas application.
|
1 2 3 4 5 6 7 8 9 |
public Set<Canvas.ContextTypeEnum> excludeContextTypes(){ Set<Canvas.ContextTypeEnum> excluded = new Set<Canvas.ContextTypeEnum>(); excluded.add(Canvas.ContextTypeEnum.ORGANIZATION); excluded.add(Canvas.ContextTypeEnum.USER); excluded.add(Canvas.ContextTypeEnum.RECORD_DETAIL); return excluded; } |
- ORGANIZATION: Exclude context information about the organization in which the canvas app is running.
- RECORD_DETAIL: Exclude context information about the object record on which the canvas app appears.
- USER: Exclude context information about the current user.
To modify the default behavior of the signed request, you need to provide an Apex class that implements onRender() and associate this class with your canvas app. In onRender() implementation, you can control app behavior with custom code.
In your onRender() implementation, you can retrieve the following context information.
In your onRender() implementation, you can retrieve the following context information.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public void onRender(Canvas.RenderContext renderContext) { Canvas.ApplicationContext app = renderContext.getApplicationContext(); Canvas.EnvironmentContext env = renderContext.getEnvironmentContext(); Double currentVersion = Double.valueOf(app.getVersion()); if (currentVersion <= 5){ throw new Canvas.CanvasRenderException('Error: Versions earlier than 5 are no longer supported.'); } app.setCanvasUrlPath('/alternatePath'); env.addEntityFields(new Set<String>{'Name','BillingAddress','YearStarted'}); Map<String, Object> previousParams = (Map<String, Object>) JSON.deserializeUntyped(env.getParametersAsJSON()); previousParams.put('newCustomParam','newValue'); env.setParametersAsJSON(JSON.serialize(previousParams)); } |
The ApplicationContext interface provides methods to retrieve application information about the canvas app that’s being rendered. The EnvironmentContext interface provides methods to retrieve environment information about the current canvas app. The OnRender method performs the following in the above code.
1.Checks the app version information and, if the version is unsupported, throws a CanvasRenderException.
2.Overrides the current canvas app URL, appending ‘/alternatePath’ to the domain portion of the original URL.
3.Sets the list of object fields
4.Overrides the set of custom parameters by adding a new ‘newCustomParam’ parameter
2.Overrides the current canvas app URL, appending ‘/alternatePath’ to the domain portion of the original URL.
3.Sets the list of object fields
4.Overrides the set of custom parameters by adding a new ‘newCustomParam’ parameter
