Class Index | File Index

Classes


Namespace Sfdc.canvas.client

Sfdc.canvas.client
Defined in: client.js.

Namespace Summary
Constructor Attributes Constructor Name and Description
 
Method Summary
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.
 
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.
 
Returns the current version of the client.
Namespace Detail
Sfdc.canvas.client
Method Detail
ajax(url, settings)
Performs a cross-domain, asynchronous HTTP request.
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"}.

Documentation generated by JsDoc Toolkit 2.4.0 on Tue Jul 15 2014 13:44:12 GMT-0700 (PDT)