lightning:workspaceAPI

This component allows you to access methods for programmatically controlling workspace tabs and subtabs in a Lightning console app. In Lightning console apps, records open as workspace tabs and their related records open as subtabs.

To access the methods, create an instance of the lightning:workspaceAPI component and assign an aura:id attribute to it.

1<lightning:workspaceAPI aura:id="workspace"/>

This example opens a new tab displaying the record with the given relative URL in the url attribute when the button is clicked.

1<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
2    <lightning:workspaceAPI aura:id="workspace" />
3    <lightning:button label="Open Tab" onclick="{! c.openTab }" />
4</aura:component>

The button in the component calls the following client-side controller.

1{(
2    openTab : function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openTab({
5            url: '#/sObject/001R0000003HgssIAC/view',
6            focus: true
7        });
8    },
9)}

This component supports the following methods. Most methods take only one argument, a JSON array of parameters. For more information on these methods, see the Console Developer Guide.

closeTab({tabId})

• tabId (string): ID of the workspace tab or subtab to close.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

focusTab({tabId})

• tabId (string): The ID of the workspace tab or subtab on which to focus.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

getAllTabInfo()

Returns a Promise. Success resolves to an array of tabInfo objects. The Promise will be rejected on error.

getFocusedTabInfo()

Returns a Promise. Success resolves to a tabInfo object. The Promise will be rejected on error.

getTabInfo({tabId})

• tabId (string): ID of the tab for which to retrieve the information.

Returns a Promise. Success resolves to a tabInfo object. The Promise will be rejected on error.

getTabURL({tabId})

• tabId (string): ID of the tab for which to retrieve the URL.

Returns a Promise. Success resolves to the tab URL. The Promise will be rejected on error.

isSubtab({tabId})

• tabId (string): ID of the tab.

Returns a Promise. Success resolves to true if the tab is a subtab, false otherwise. The Promise will be rejected on error.

isConsoleNavigation()

Returns a Promise. Success resolves to true if console navigation is present, false otherwise. The Promise will be rejected on error.

getEnclosingTabId()

Returns a Promise. Success resolves to the enclosing tabId or false if not within a tab. The Promise will be rejected on error.

openSubtab({parentTabId, url, recordId, focus})

• parentTabId (string): ID of the workspace tab within which the new subtab should open.
• url (string): Optional. The URL representing the content of the new subtab. URLs can be either relative or absolute.
• recordId (string): Optional. A record ID representing the content of the new subtab.
• focus (boolean): Optional. Specifies whether the new subtab has focus.

Returns a Promise. Success resolves to the tabId of the subtab. The Promise will be rejected on error.

openTab({url, recordId, focus})

• url (string): Optional. The URL representing the content of the new tab. URLs can be either relative or absolute.
• recordId (string): Optional. A record ID representing the content of the new tab.
• focus (boolean): Optional. Specifies whether the new tab has focus.
• overrideNavRules (boolean): Optional. Specifies whether to override nav rules when opening the new tab.

Returns a Promise. Success resolves to the tabId of the workspace. The Promise will be rejected on error.

setTabIcon({tabId, icon, iconAlt})

• tabId (string): The ID of the tab for which to set the icon.
• icon (string): An SLDS icon key. See a full list of icon keys on the SLDS reference site.
• iconAlt (string): Optional. Alternative text for the icon.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabLabel({tabId, label})

• tabId (string): The ID of the tab for which to set the label.
• label (string): The label of the workspace tab or subtab.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabHighlighted({tabId, highlighted})

• tabId (string): The ID of the tab for which to highlight.
• highlighted (boolean): Specifies whether the new tab should be highlighted.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.