Interacting with the Hosted Portal
Introduction
In any front-end environment where the Buyer Portal is being loaded, the global b2b object exposes an API that can be used to interact with the Buyer Portal app and its data.
This library of JavaScript global objects allows you to interact with the Buyer Portal in various ways from outside the React app itself, giving you the flexibility to use your own client-side code to perform tasks like opening a specific Buyer Portal page, adding a product to the current draft quote, or get information about the currently logged-in user.
Customization with the JavaScript API
The global JavaScript utilities make it possible to pursue a strategy for storefront customization without having to fork the Buyer Portal application code. This strategy is viable if your customization requirements are relatively simple and involve interacting with the B2B entities on typical storefront pages. Examples might include:
- Displaying B2B data on standard storefront pages (for example, a product detail page).
- Opening a Buyer Portal page from user actions on other pages.
- Adding a product configuration to the current draft quote based on a custom action.
The global utilities don’t expose access to the Buyer Portal’s own component structure, so it is not a viable choice for altering the UI of the Buyer Portal itself.
When building storefront customizations that interact with the Buyer Portal, the question arises: Where should your custom JavaScript live?
While it might be a natural choice to integrate your B2B-dependent code into the rest of your storefront theme, this presents a challenge in Stencil: Loading the Buyer Portal is not supported in a local dev environment using the Stencil CLI. This means JS that interacts with the Buyer Portal cannot be directly tested in the Stencil dev environment.
Instead, a good practice is to adopt the same strategy the Buyer Portal itself uses: Inject your B2B-dependent code into the storefront using external scripts. Following this model, development works the same way as with a forked Buyer Portal (as we’ll see later): Run your custom JS application in its own local dev environment, and inject it into a sandbox storefront.
This is the strategy we’ll be using in the lab exercises for this section.
In Catalyst
You have more flexibility for your strategy with Buyer Portal dependent JavaScript in the available Catalyst integration. Due to Catalyst being a fully decoupled storefront application, the Buyer Portal will load in any environment, including a local development environment. You might choose to access the global Buyer Portal utilities directly in your Catalyst components or via separate app as described.
b2b.utils Example
The Buyer Portal’s JavaScript API is available as the window.b2b.utils object. (You must make sure the Buyer Portal has been initialized and the b2b object is available before invoking it!)
In a storefront with the Buyer Portal loaded, use window.b2b.utils in the console of your browser dev tools to inspect the available utilities.
As an initial example, the openPage function can be used to navigate to a specific Buyer Portal page or even close the Buyer Portal interface.
Example Code:
The above will open the Invoice page of the Buyer Portal.
The entire Buyer Portal interface can be closed, returning the user to the page matching the current URL, with the following:
See the HeadlessRoutes constant in the Buyer Portal source code for the full list of valid keys that can be passed to openPage.
