Using Page References to Open Console Workspace Tabs and Subtabs

Use openTab() and openSubtab() with a lightning:isUrlAddressible component to open custom Lightning components in Lightning console apps.

lightning:isUrlAddressable provides the following benefits over force:navigateToComponent for console apps:

Future-proofs your apps from changes in URL formats.
Generates a user-friendly URL for your tabs.
Opens a Lightning component as a subtab, even if called from a utility, a hover, or another page.
Allows a mechanism to conditionally open a given component more than once or redirect to an already open workspace or subtab using the uid parameter.

To create a page reference we can use to open workspace tabs and subtabs, let’s create greetings.cmp, and implement lightning:isUrlAddressible. This component displays “Hello, <name>” where a URL parameter, c__name, provides the name when the component is opened. The component also defines a pageReference that we can use to navigate to it.

1<aura:component implements="lightning:isUrlAddressable">
2    <aura:attribute name="name" type="String" description="The person that will be greeted" />
3    <aura:handler name="init" value="{!this}" action="{!c.init}" />
4    <aura:handler name="change" value="{!v.pageReference}" action="{!c.handlePageChange}" />
5    <h1>Greeting Page</h1>
6    <div>Hello, {!v.name}</div>
7</aura:component>

The JavaScript controller greetingsController.js handles URL parameters in the init method and assigns the name attribute using that URL parameter.

1({
2    init: function(cmp, evt, hlp) {
3        var myPageRef = cmp.get("v.pageReference");
4        var name = myPageRef && myPageRef.state ? myPageRef.state.c__name : "World";
5        cmp.set("v.name", name);
6    },
7    handlePageChange: function(cmp, evt, hlp) {
8        var myPageRef = cmp.get("v.pageReference");
9        var name = myPageRef && myPageRef.state ? myPageRef.state.c__name : "World";
10        cmp.set("v.name", name);
11    }
12})

Now let’s create openGreetings.cmp, which includes an input field to set the c__name URL parameter when we open greetings.cmp.

1<aura:component>
2    <aura:attribute name="pageReference" type="Object"/>
3    <lightning:navigation aura:id="navService"/>
4    <lightning:button label="Open Greeting in Subtab" onclick="{!c.openSubtab}"/>
5    <lightning:input label="Name" name="myname"/>
6</aura:component>

The controller openGreetingsController.js uses openSubtab() and sets c__name to the value of the myname input field. You can use the uid parameter to conditionally dedupe tabs and subtabs. Omit the uid to open a new tab or subtab every time.

1({
2    openSubtab: function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openSubtab({
5            pageReference: {
6                "type": "standard__component",
7                "attributes": {
8                    "componentName": "c__greetings"
9                },
10                "state": {
11                    "uid": "1",
12                    "c__name": component.get("v.myName")
13                }
14            }
15        }).then(function(tabId) {
16            console.log("The new subtab ID is:" + tabId);
17        }).catch(function(error) {
18            console.log("error");
19        });
20    }
21})

Now that we have everything set up, we can test our components by creating a custom tab in Setup for openGreetings.cmp. Add the custom tab to a console app and open the console app. Select the custom tab from the nav menu to open openGreetings.cmp. Enter a name and click “Open Geeting in Subtab.” greetings.cmp opens as a subtab and displays its greeting with the provided name.

Salesforce Console Developer Guide

Using Page References to Open Console Workspace Tabs and Subtabs

See Also