Lightning Web Components (LWC) have come a long way since the feature was first launched back in 2019. As the framework and the collection of base components evolve, there are still a few gaps that remain with the Lightning framework (Aura). The Workspace API was one of those few gaps, but it’s been closed since the Spring ’24 release thanks to the GA of a dedicated lightning/platformWorkspaceApi LWC module that replaces the legacy lightning:workspaceAPI component.
In this post, we’ll do a refresher on console apps and the Workspace API, then we’ll present how you can get started with the platformWorkspaceApi LWC module using our LWC Recipes sample app.
About console apps and the Workspace API
Lightning Experience offers two types of navigation for the Lightning app: standard and console navigation. In standard navigation apps (item #1 in the screenshot below), you open a single record at a time. However, with console navigation (item #2), you can open several records at a time while keeping a list view pinned, and navigate between related records using subtabs.
With console apps, you can work with multiple records more efficiently. Such apps, like the Service Console, are a great solution for fast-paced environments like support centers.
To get the most out of console apps, you can configure how navigation works in custom components thanks to the Workspace API. This API provides context about open tabs and subtabs, and it allows you to trigger various actions, such as opening new tabs, changing labels, adding icons, and highlighting tabs.
Interact with the Workspace API from LWC
Since the GA of the lightning/platformWorkspaceApi module in Spring ’24, you can control console navigation programmatically with LWC without the need for Lightning (Aura).
Our developer advocate colleague Alba Rivas has prepared a set of recipes for our LWC Recipes sample app that demonstrate the many capabilities of the lightning/platformWorkspaceApi module. If you try a recent version of the app, you’ll notice a new LWC Recipes Console app that holds these new Workspace API recipes.
Each of these recipes demonstrates a simple scenario in which you control the console navigation with the Workspace API along with the related tests.
Control console navigation with the Workspace API
Let’s take a look at the code of a simple example: how to open a new tab with the workspaceAPIOpenTab recipe. Here’s the JavaScript of our component:
Whenever you want to use the Workspace API, the first thing that you need to do is to ensure that your component is displayed in a console app. To check this, import the IsConsoleNavigation wire and check that its value is true. In the example above, we return and do nothing if we’re not in a console app.
Once you’ve made sure that you’re in a console app, you can safely call any of the lightning/platformWorkspaceApi methods, such as openTab like in the example. Note the async/await statements as all the methods in the lightning/platformWorkspaceApi module are asynchronous and return promises.
Test your Workspace API calls
Since all good developers test their code, you can also learn from LWC Recipes how to test your Workspace API calls. If we continue to explore the same workspaceAPIOpenTab recipe, you can navigate to the recipe’s test code as follows.
As in most LWC tests, you start by creating your component and attaching it to the test page. Remember at this point that LWC Jest tests don’t run in a real browser that is connected to the internet. Jest tests run in a local virtual browser thanks to JSDOM. This means that you don’t have access to Lightning Experience and the real lightning/platformWorkspaceApi module. Instead, you rely on a stub for your tests.
You use this stub to simulate the console navigation app by emitting true as the mock response of the IsConsoleNavigation wire. Then, you can continue with the test: finding the button that triggers the action, clicking it, and finally, checking that your openTab mock was called with the expected values.
Conclusion
That’s it for our refresher on console navigation apps and the Workspace API. We shared how you can get started fast with the lightning/platformWorkspaceApi module using the LWC Recipes sample app.
It’s now time to look back at legacy code and consider moving away from the Lightning (Aura) lightning:workspaceAPI component and replacing it with the modern LWC module.
Resources
About the author
Philippe Ozil is a Principal Developer Advocate at Salesforce where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working with APIs, DevOps, robotics, and VR projects. Follow him on X @PhilippeOzil, on LinkedIn @PhilippeOzil, or check out his GitHub projects @pozil.