Theme Context and Loader Reference
When your theme is loaded, Spiff Commerce provides it with a context describing how it was launched, and a loader for communicating back to the platform. Both are defined by @spiffcommerce/theme-bridge.
import type { ThemeContext, SpiffThemeLoader } from "@spiffcommerce/theme-bridge";
The loader is available on the window object as SpiffThemeLoader. See Getting Started for how to wire it up.
ThemeContext
Themes are launched with a bundle context. Every context contains the following fields.
| Name | Type | Description |
|---|---|---|
type | "bundle" | Differentiates the members of the ThemeContext union. |
applicationKey | string | The application key used to configure the SpiffCommerceClient. |
configuration | ThemeInstallConfigurationResource | The configuration provided by the integration. |
container | HTMLElement | The element to render your theme into. |
activation | ActivationData? | The activation the theme was launched within. |
bundleOptions | ThemeContextBundleOptions | Describes the bundle to open. See below. |
currency | string? | The ISO 4217 currency code to present prices in. |
embedMode | boolean? | Whether the theme is embedded into the main page content or displayed in a modal. |
queryParams | { [key: string]: string }? | Query parameters that were passed to the editor and passed through to the theme. |
Bundle options
bundleOptions is either an existing bundle to reopen, or a new bundle to create.
Existing bundle (type: "existing")
| Name | Type | Description |
|---|---|---|
bundleId | string | The ID of the bundle to reopen. |
Load it with client.getExistingBundle(bundleId).
New bundle (type: "new")
| Name | Type | Description |
|---|---|---|
productCollectionId | string? | The product collection the customer chooses products from. |
integrationProductId | string? | An initial integration product, if one was preselected (for example by the product page that launched the theme). |
singleProductMode | boolean? | When true, the customer configures exactly one product from the activation's collection. |
collectionProduct | CollectionProduct? | The product being configured. Use this to determine workflows. Only present when singleProductMode is true. |
Create it with client.getNewBundle(productCollectionId, initialMetadata, options, activation?.id).
SpiffThemeLoader
| Method | Description |
|---|---|
getContext(): Promise<ThemeContext> | Retrieves the theme context. If it isn't available yet, the promise resolves when it is. |
configureClient(client: SpiffCommerceClient) | Configures a SpiffCommerceClient with the settings required to communicate with the Spiff Commerce API. |
themeLoaded() | Notifies the platform that your theme has loaded. This hides the loading indicator and lets the customer interact with the theme. |
close() | Closes the theme and exits the platform. The session is treated as cancelled. |
addToEcommerceCart(message) | Sends the finished design to the e-commerce platform and ends the session. Pass the result of bundle.finish(). |
completeQuote(message?) | Signals that a quote has been completed. The message contains the quoteId, and optionally the bundleId and bundleOwnerId. |
navigateToCustomerPortal() | Navigates away from the theme and launches the Customer Portal. This immediately exits your session. |
Single product mode
When an activation is in single product mode, the theme is launched with singleProductMode: true and a collectionProduct. Create the bundle as normal, add the product's workflow experience to it, and skip any product selection UI. apps/corporate-theme/src/bundles/attemptLoad.ts in the gaia repository is a complete reference implementation of resolving the bundle, product and workflow from the context.