You can control your app lifecycle by providing an implementation of the Canvas.CanvasLifecycleHandler Apex interface that Salesforce can use.
The Apex Canvas.CanvasLifecycleHandler interface provides methods and callbacks for customizing app lifecycle behavior. Salesforce will use your implementation at runtime to let you run custom code. Use the following steps to create an implementation of the Canvas.CanvasLifecycleHandler interface.
- From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
- Click New to create a Apex class.
- Create an Apex class that implements the Canvas.CanvasLifecycleHandler interface. You must implement the excludeContextTypes() and onRender() methods. Here’s a template example:public class
MyCanvasLifecycleHandler implements Canvas.CanvasLifecycleHandler {
public Set<Canvas.ContextTypeEnum> excludeContextTypes()
{
Set<Canvas.ContextTypeEnum> excluded = new Set<Canvas.ContextTypeEnum>();
// Code goes here to add items to excluded list
// that should be excluded from Context data
return excluded;
}
public void onRender(Canvas.RenderContext renderContext) {
// Code goes here to customize behavior when the app is rendered
}
}
>> After you’ve finished adding your code, save the Apex class
>> Optionally test your implementation by using the Canvas.Test class
>> To let Salesforce know which implementation to use for your app, associate your Apex class with your app.
To modify the default behavior of the signed request, you need to provide an Apex class that implements Canvas.CanvasLifecycleHandler.onRender() and associate this class with your canvas app. In your onRender() implementation, you can control app behavior with custom code.
Salesforce calls your implementation of onRender() just before your app is rendered. Current context information is passed to this method in the Canvas.RenderContext parameter.
In your
onRender() implementation, you can retrieve the following context information.
- Application context data, such as the canvas app name, URL, version, and namespace.
- Environment context data, such as the display location and sublocation, object field names, and custom parameters.
You can set the following context information.
- The portion of the canvas app URL after the app domain.
- The list of object fields for which Salesforce will return Record context data if the canvas app appears on an object page. One way a canvas app can appear on an object page is if the canvas app appears on a Visualforce page through the use of the <apex:canvasApp> component and that Visualforce page is associated with an object.
- The custom parameters that are passed to the canvas app.
You can also use Canvas.CanvasRenderException to present an error message to the user in the Salesforce by throwing a Canvas.CanvasRenderException.
Here’s an example onRender() implementation that:
- Checks the app version information and, if the version is unsupported, throws a CanvasRenderException.
- Overrides the current canvas app URL, appending ‘/alternatePath’ to the domain portion of the original URL.
- Sets the list of object fields to include Name, BillingAddress, and YearStarted, anticipating that the canvas app will appear on the Account page.
- Overrides the set of custom parameters by adding a new ‘newCustomParam’ parameter. Note that the current set of parameters is first retrieved and cached locally. The new parameter is added to the cached list to ensure that you don’t lose the current set of custom parameters when you call setParametersAsJSON().
- public void onRender(Canvas.RenderContext renderContext) {
// Get the Application and Environment context from the RenderContext
Canvas.ApplicationContext app = renderContext.getApplicationContext();
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
// Check the application version
Double currentVersion = Double.valueOf(app.getVersion());
if (currentVersion <= 5){
// Versions lower than 5 are no longer supported in this example
throw new Canvas.CanvasRenderException('Error: Versions earlier than 5 are no longer supported.');
}
// Override app URL, replacing portion after domain with '/alternatePath'
app.setCanvasUrlPath('/alternatePath');
// Add Name, BillingAddress and YearStarted to fields
// (assumes we'll run from a component on the Account detail page)
Set<String> fields = new Set<String>{'Name','BillingAddress','YearStarted'};
env.addEntityFields(fields);
// Add a new custom param to the set of custom params
// First, get the current custom params
Map<String, Object> previousParams =
(Map<String, Object>) JSON.deserializeUntyped(env.getParametersAsJSON());
// Add a 'newCustomParam' to our Map
previousParams.put('newCustomParam','newValue');
// Now, replace the parameters
env.setParametersAsJSON(JSON.serialize(previousParams));
}
