Add a Salesforce Console Component To Your App, Part 2
Ok, so you've read part one of this two-parter and you've got a console component that puts your Visualforce page into the Salesforce console, so what's next? Well all of the integration with the console itself is done via a Javascript API, so as always reading the documentation is a great place to start. It's broken down neatly into sections for different styles of interaction, but I want to call out some of the basics here so that you can get struck straight in (because the deep end is always fun, right?).
Are You In?
First up, it's probably a good idea to find out if our page is indeed being viewed in the console, and as you'd expect (or at least hope) it's very easy to find that out. First we have to include a script in the Visualforce page that provide access to the console API:
<script src="/support/console/32.0/integration.js" type="text/javascript"></script>
Now, in our own Javascript we can call the rather conveniently named function, isInConsole(). Care to guess how that function works? It's pretty much (I've not checked everything) the only function in this API that is synchronous, everything else uses callbacks.
<script type="text/javascript">
if(sforce.console.isInConsole())
{
console.log('Hello, Console!');
}
</script>
Basic Top Level Interactions
Console components are added as buttons in a bar across the bottom of the screen, and the page embedded in the component is displayed when the user clicks on said buttons. Detecting that button click is nice and simple, though now we need to use a callback, and as per the documentation this callback function provides a parameter that includes two properties, one of which is particularly helpful, windowHidden, which lets you know which state the component window is now in.
sforce.console.onCustomConsoleComponentButtonClicked(function(result)
{
if(!result.windowHidden)
{
console.log('Window is on screen.');
}
});
Of course, before we get tangled up in the callback Christmas tree it might be an idea to use a variable to store your anonymous function and keep the code flatter. This doesn't appear to make much of a difference right now, but if you were to call another method involving a callback inside of the anonymous function above the you'd see the nesting get deeper and more confusing.
var onButtonClicked = function(result)
{
if(!result.windowHidden)
{
console.log('Window is on screen.');
}
}
sforce.console.onCustomConsoleComponentButtonClicked(onButtonClicked);
There are some other neat things we can do with the console button, such as flashing the text (with great power...), scrolling the button text, and a whole lot more. Check out the section of the documentation entitled "Methods for Application-Level Custom Console Components" for more fun.
Navgation Interactions
Of potentially more interesting is effecting changes in what the user is viewing, or reacting to them.
For the former, there are many methods available involing setting to focus to tabs already on the screen (you can get the IDs for these tabs via other methods) but there are two particularly useful methods for actually opening new tabs, openPrimaryTab() and openSubtab(). These let you open up particular records for the user. Both of these take a few parameters, including the URL to display and boolean to control whether or not focus is shifted to them immediately or not.
var onOpenPrimaryTab = function(result)
{
if(result.success)
{
// ok, you get the idea.
}
}
// params:
// tab id (null for new tab), url, focus?, the tab title, our callback
sforce.console.openPrimaryTab(null, '/apex/MyOtherVFPage', true, 'The Title', onOpenPrimaryTab);
The code above used null for the first parameter to create a new tab, but we could easily have provided a tab ID (there's that term again) to replace the content of an existing tab. How do you get those IDs? getFocusedPrimaryTabId() is the most obvious way if you want to know what the user is looking at, but there is also getPrimaryTabIds() (note the plural) and some other functions depending on whether your page is outside of a custom component and in a tab itself.
Finally a useful technique for some applications will be performing some action based on when the user changes tabs themselves, and to this end there are methods available to respond to both primary and subtab changes:
var primaryTabFocused = function(result)
{
if(result.objectId != null)
{
console.log('User is viewing record: ' + result.objectId;
}
}
sforce.console.onFocusedPrimaryTab(primaryTabFocused);
Other Functionality
I've barely scratched the surface of what you can do in the console in this post, but frankly there's little point in me giving examples of more as the API documentation does a great job of explaining what can be done, and as you may have noticed everything is named in a concise and sensible manner.
Two major areas that you may want to look into depending on your scenario are:
Hopefully this whirlwind tour has at least kicked off some ideas for console integration in your application, it's something all too easily overlooked despite being extremely powerful. Happy coding in 2015!