Controlling Canvas App Behavior

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().

1public void onRender(Canvas.RenderContext renderContext) {
2
3    // Get the Application and Environment context from the RenderContext
4    Canvas.ApplicationContext app = renderContext.getApplicationContext();
5    Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
6
7    // Check the application version
8    Double currentVersion = Double.valueOf(app.getVersion());
9    if (currentVersion <= 5){
10        // Versions lower than 5 are no longer supported in this example
11        throw new Canvas.CanvasRenderException('Error: Versions earlier than 5 are no longer supported.');
12    }
13
14    // Override app URL, replacing portion after domain with '/alternatePath'
15    app.setCanvasUrlPath('/alternatePath');
16
17    // Add Name, BillingAddress and YearStarted to fields 
18    // (assumes we'll run from a component on the Account detail page)
19    Set<String> fields = new Set<String>{'Name','BillingAddress','YearStarted'};
20    env.addEntityFields(fields);
21
22    // Add a new custom param to the set of custom params
23    // First, get the current custom params
24    Map<String, Object> previousParams = 
25        (Map<String, Object>) JSON.deserializeUntyped(env.getParametersAsJSON());
26    // Add a 'newCustomParam' to our Map
27    previousParams.put('newCustomParam','newValue');
28    // Now, replace the parameters
29    env.setParametersAsJSON(JSON.serialize(previousParams));
30}

Canvas Developer Guide

Controlling Canvas App Behavior