Namespace Sfdc.canvas.client
Sfdc.canvas.client
Defined in: client.js.
Constructor Attributes | Constructor Name and Description |
---|---|
Method Attributes | Method Name and Description |
---|---|
ajax(url, settings)
Performs a cross-domain, asynchronous HTTP request.
|
|
autogrow(client, b, interval)
Starts or stops a timer which checks the content size of the iFrame and
adjusts the frame accordingly.
|
|
ctx(clientscb, client)
Returns the context for the current user and organization.
|
|
publish(client, e)
Publishes a custom event.
|
|
refreshSignedRequest(clientscb)
Refresh the signed request.
|
|
repost(refresh)
Repost the signed request.
|
|
resize(client, size)
Informs the parent window to resize the canvas iFrame.
|
|
Temporary storage for the signed request.
|
|
size()
Returns the current size of the iFrame.
|
|
subscribe(client, s)
Subscribes to parent or custom events.
|
|
token(t)
Stores or gets the oauth token in a local javascript variable.
|
|
unsubscribe(client, s)
Unsubscribes from parent or custom events.
|
|
version()
Returns the current version of the client.
|
Method Detail
ajax(url, settings)
Performs a cross-domain, asynchronous HTTP request.
Note: this method shouldn't be used for same domain requests.
Note: this method shouldn't be used for same domain requests.
//Posting to a Chatter feed: var sr = JSON.parse('<%=signedRequestJson%>'); var url = sr.context.links.chatterFeedsUrl+"/news/" +sr.context.user.userId+"/feed-items"; var body = {body : {messageSegments : [{type: "Text", text: "Some Chatter Post"}]}}; Sfdc.canvas.client.ajax(url, {client : sr.client, method: 'POST', contentType: "application/json", data: JSON.stringify(body), success : function(data) { if (201 === data.status) { alert("Success" } } });
// Gets a list of Chatter users: // Paste the signed request string into a JavaScript object for easy access. var sr = JSON.parse('<%=signedRequestJson%>'); // Reference the Chatter user's URL from Context.Links object. var chatterUsersUrl = sr.context.links.chatterUsersUrl; // Make an XHR call back to Salesforce through the supplied browser proxy. Sfdc.canvas.client.ajax(chatterUsersUrl, {client : sr.client, success : function(data){ // Make sure the status code is OK. if (data.status === 200) { // Alert with how many Chatter users were returned. alert("Got back " + data.payload.users.length + " users"); // Returned 2 users } })};
- Parameters:
- {String} url
- The URL to which the request is sent
- {Object} settings
- A set of key/value pairs to configure the request
The success setting is required at minimum and should be a callback function - {String} settings.client Optional
- The required client context {oauthToken: "", targetOrigin : "", instanceId : ""}
- {String} settings.contentType Optional
- "application/json"
- {String} settings.data Optional
- The request body
- {String} settings.headers Optional
- request headers
- {String} settings.method Optional, Default: "GET"
- The type of AJAX request to make
- {Function} settings.success Optional
- Callback for all responses from the server (failure and success). Signature: success(response); interesting fields: [response.data, response.responseHeaders, response.status, response.statusText}
- {Boolean} settings.async Optional, Default: true
- Asynchronous: only
true
is supported.
- Throws:
- An error if the URL is missing or the settings object doesn't contain a success callback function.
autogrow(client, b, interval)
Starts or stops a timer which checks the content size of the iFrame and
adjusts the frame accordingly.
Use this function when you know your content is changing size, but you're not sure when. There's a delay as
the resizing is done asynchronously. Therfore, if you know when your content changes size, you should
explicitly call the resize() method and save browser CPU cycles.
Note: you should turn off scrolling before this call, otherwise you might get a flicker.
// Turn on auto grow with default settings. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.autogrow(sr.client); }); // Turn on auto grow with a polling interval of 100ms (milliseconds). Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.autogrow(sr.client, true, 100); }); // Turn off auto grow. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.autogrow(sr.client, false); });
- Parameters:
- {client} client
- The object from the signed request
- {boolean} b
- Whether it's turned on or off; defaults to
true
- {Integer} interval
- The interval used to check content size; default timeout is 300ms.
ctx(clientscb, client)
Returns the context for the current user and organization.
// Gets context in the canvas app. function callback(msg) { if (msg.status !== 200) { alert("Error: " + msg.status); return; } alert("Payload: ", msg.payload); } var ctxlink = Sfdc.canvas.byId("ctxlink"); var client = Sfdc.canvas.oauth.client(); ctxlink.onclick=function() { Sfdc.canvas.client.ctx(callback, client)}; }
- Parameters:
- {Function} clientscb
- The callback function to run when the call to ctx completes
- {Object} client
- The signedRequest.client.
publish(client, e)
Publishes a custom event. Events are published to all subscribing canvas applications
on the same page, regardless of domain. Choose a unique namespace so the event doesn't collide with other
application events. Events can have payloads of arbitrary JSON objects.
// Publish the foo.bar event with the specified payload. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.publish(sr.client, {name : "foo.bar", payload : {some : 'stuff'}}); });
- Parameters:
- {client} client
- The object from the signed request
- {Object} e
- The event to publish
refreshSignedRequest(clientscb)
Refresh the signed request. Obtain a new signed request on demand. Note the
authentication mechanism of the canvas app must be set to SignedRequest and not OAuth.
// Gets a signed request on demand. Sfdc.canvas.client.refreshSignedRequest(function(data) { if (data.status === 200) { var signedRequest = data.payload.response; var part = signedRequest.split('.')[1]; var obj = JSON.parse(Sfdc.canvas.decode(part)); } }
- Parameters:
- {Function} clientscb
- The client's callback function to receive the base64 encoded signed request.
repost(refresh)
Repost the signed request. Instruct the parent window to initiate a new post to the
canvas url. Note the authentication mechanism of the canvas app must be set to SignedRequest and not OAuth.
// Gets a signed request on demand, without refreshing the signed request. Sfdc.canvas.client.repost(); // Gets a signed request on demand, first by refreshing the signed request. Sfdc.canvas.client.repost({refresh : true});
- Parameters:
- {Boolean} refresh Optional, Default: false
- Refreshes the signed request when set to true.
resize(client, size)
Informs the parent window to resize the canvas iFrame. If no parameters are specified,
the parent window attempts to determine the height of the canvas app based on the
content and then sets the iFrame width and height accordingly. To explicitly set the dimensions,
pass in an object with height and/or width properties.
//Automatically determine the size Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.resize(sr.client); });
//Set the height and width explicitly Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.resize(sr.client, {height : "1000px", width : "900px"}); });
//Set only the height Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.resize(sr.client, {height : "1000px"}); });
- Parameters:
- {Client} client
- The object from the signed request
- {size} size
- The optional height and width information
{Object}
signedrequest(s)
Temporary storage for the signed request. An alternative for users storing SR in
a global variable. Note: if you would like a new signed request take a look at refreshSignedRequest().
- Parameters:
- {Object} s
- signedrequest to be temporarily stored in Sfdc.canvas.client object.
- Returns:
- {Object} the value previously stored
{Object}
size()
Returns the current size of the iFrame.
//get the size of the iFrame and print out each component. var sizes = Sfdc.canvas.client.size(); console.log("contentHeight; " + sizes.heights.contentHeight); console.log("pageHeight; " + sizes.heights.pageHeight); console.log("scrollTop; " + sizes.heights.scrollTop); console.log("contentWidth; " + sizes.widths.contentWidth); console.log("pageWidth; " + sizes.widths.pageWidth); console.log("scrollLeft; " + sizes.widths.scrollLeft);
- Returns:
- {Object}
heights.contentHeight
: the height of the virtual iFrame, all content, not just visible content.
heights.pageHeight
: the height of the visible iFrame in the browser.
heights.scrollTop
: the position of the scroll bar measured from the top.
widths.contentWidth
: the width of the virtual iFrame, all content, not just visible content.
widths.pageWidth
: the width of the visible iFrame in the browser.
widths.scrollLeft
: the position of the scroll bar measured from the left.
subscribe(client, s)
Subscribes to parent or custom events. Events
with the namespaces 'canvas', 'sfdc', 'force', 'salesforce', and 'chatter' are reserved by Salesforce.
Developers can choose their own namespace and event names.
Event names must be in the form
namespace.eventname
.
// Subscribe to the parent window onscroll event. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); // Capture the onScrolling event of the parent window. Sfdc.canvas.client.subscribe(sr.client, {name : 'canvas.scroll', onData : function (event) { console.log("Parent's contentHeight; " + event.heights.contentHeight); console.log("Parent's pageHeight; " + event.heights.pageHeight); console.log("Parent's scrollTop; " + event.heights.scrollTop); console.log("Parent's contentWidth; " + event.widths.contentWidth); console.log("Parent's pageWidth; " + event.widths.pageWidth); console.log("Parent's scrollLeft; " + event.widths.scrollLeft); }} ); });
// Subscribe to a custom event. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.subscribe(sr.client, {name : 'mynamespace.someevent', onData : function (event) { console.log("Got custom event ", event); }} ); });
// Subscribe to multiple events Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.subscribe(sr.client, [ {name : 'mynamespace.someevent1', onData : handler1}, {name : 'mynamespace.someevent2', onData : handler2}, ]); });
//Subscribe to Streaming API events. //The PushTopic to subscribe to must be passed in. //The 'onComplete' method may be defined, //and will fire when the subscription is complete. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); var handler1 = function(){ console.log("onData done");}, handler2 = function(){ console.log("onComplete done");}; Sfdc.canvas.client.subscribe(sr.client, {name : 'sfdc.streamingapi', params:{topic:"/topic/InvoiceStatements"}}, onData : handler1, onComplete : handler2} ); });
- Parameters:
- {client} client
- The object from the signed request
- {Object} s
- The subscriber object or array of objects with name and callback functions
{Object}
token(t)
Stores or gets the oauth token in a local javascript variable. Note, if longer term
(survive page refresh) storage is needed store the oauth token on the server side.
- Parameters:
- {String} t
- oauth token, if supplied it will be stored in a volatile local JS variable.
- Returns:
- {Object} the oauth token.
unsubscribe(client, s)
Unsubscribes from parent or custom events.
//Unsubscribe from the canvas.scroll method. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.unsubscribe(sr.client, "canvas.scroll"); });
//Unsubscribe from the canvas.scroll method by specifying the object name. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.unsubscribe(sr.client, {name : "canvas.scroll"}); });
//Unsubscribe from multiple events. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.unsubscribe(sr.client, ['canvas.scroll', 'foo.bar']); });
//Unsubscribe from Streaming API events. //The PushTopic to unsubscribe from must be passed in. Sfdc.canvas(function() { sr = JSON.parse('<%=signedRequestJson%>'); Sfdc.canvas.client.unsubscribe(sr.client, {name : 'sfdc.streamingapi', params:{topic:"/topic/InvoiceStatements"}}); });
- Parameters:
- {client} client
- The object from the signed request
- {Object} s
- The events to unsubscribe from
{Object}
version()
Returns the current version of the client.
- Returns:
- {Object} {clientVersion : "29.0", parentVersion : "29.0"}.