Using Page References to Open Console Workspace Tabs and Subtabs

Use openTab() and openSubtab() with a lightning:isUrlAddressible component to open custom Aura 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 an Aura 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.
Other uses for the uid parameter that are not explicitly outlined in this document are not supported.
Warning

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:workspaceAPI aura:id="workspace"/>
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.getEnclosingTabId().then(function(enclosingTabId) {
5            workspaceAPI.openSubtab({
6                parentTabId: enclosingTabId,
7                pageReference: {
8                    "type": "standard__component",
9                    "attributes": {
10                        "componentName": "c__greetings"
11                    },
12                    "state": {
13                        "uid": "1",
14                        "c__name": component.get("v.myName")
15                    }
16                }
17            }).then(function(subtabId) {
18                console.log("The new subtab ID is:" + subtabId);
19            }).catch(function(error) {
20                console.log("error");
21            });
22        });
23    }
24})

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 Greeting 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