As of v1.61.0, orchestration events are no longer needed. Please visit the new Commerce Widget page for details.
Orchestrating widgets
Event orchestration is a way to transition from one widget to another by listening to different orchestration events in your application. The Wallet widget provides entrypoints into other widgets and these will need to be connected together to facilitate a seamless transition from the wallet to other widgets.
In this step-by-step guide, we will show you how you can transition from Wallet widget to Swap widget using orchestration events.
Create the Wallet and Swap widgets
To get started, make sure to follow the widget setup guide.
Create the wallet and swap widgets, then mount the wallet in your application:
- React
- JavaScript
import { useEffect, useState } from 'react';
import { checkout } from '@imtbl/sdk';
// create Checkout SDK
const checkoutSDK = new checkout.Checkout();
export function App() {
const [wallet, setWallet] =
useState<checkout.Widget<typeof checkout.WidgetType.WALLET>>();
const [swap, setSwap] =
useState<checkout.Widget<typeof checkout.WidgetType.SWAP>>();
// Initialise widgets, create wallet widget
useEffect(() => {
(async () => {
const widgets = await checkoutSDK.widgets({
config: { theme: checkout.WidgetTheme.DARK },
});
const wallet = widgets.create(checkout.WidgetType.WALLET)
const swap = widgets.create(checkout.WidgetType.SWAP)
setWallet(wallet);
setSwap(swap);
wallet.mount("wallet")
})();
}, []);
return (
<>
<div id="wallet" />
<div id="swap" />
</>
);
}
<html>
<head>
<!-- Load the SDK from jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/sdk.js"></script>
</head>
<body>
<div id="wallet"></div>
<script>
// Initialize Checkout SDK
var checkout;
(async function () {
checkout = new ImmutableCheckout.Checkout();
const widgets = await checkout.widgets({
config: { theme: ImmutableCheckout.WidgetTheme.DARK },
});
const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
const swap = widgets.create(ImmutableCheckout.WidgetType.SWAP);
wallet.mount('wallet');
})();
</script>
</body>
</html>
Listen to orchestration events
When a user clicks on Swap IMX option in the Wallet widget, an orchestration event is raised.
The orchestration event for Swap widget is request-swap
.
Assuming you have created a wallet widget called 'wallet' and a swap widget called 'swap'. Add a listener for the orchestration event 'request-swap', then handle it by unmounting the wallet and mounting the swap with parameters
- React
- JavaScript
import { checkout } from '@imtbl/sdk';
// @ts-ignore When creating the widget, pass in the configuration
const wallet = widgets.create(checkout.WidgetType.WALLET,{
config: { theme: checkout.WidgetTheme.DARK }
});
// @ts-ignore
const swap = widgets.create(checkout.WidgetType.SWAP,{
config: { theme: checkout.WidgetTheme.DARK }
});
wallet.addListener(checkout.OrchestrationEventType.REQUEST_SWAP, (data: checkout.RequestSwapEvent) => {
wallet.unmount();
swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
})
wallet.addListener('request-swap', (data) => {
wallet.unmount();
swap.mount('swap', {fromContractAddress: data.fromTokenAddress})
})
Once the event is raised and handled, the Swap widget will open with the selected token pre-populated for swap.
Sample Code
When a user clicks on Swap IMX option in the Wallet widget, an orchestration event is raised.
The orchestration event for Swap widget is request-swap
.
- React
- JavaScript
import { useEffect, useState } from 'react';
import { checkout } from '@imtbl/sdk';
// create Checkout SDK
const checkoutSDK = new checkout.Checkout();
export function App() {
const [wallet, setWallet] =
useState<checkout.Widget<typeof checkout.WidgetType.WALLET>>();
const [swap, setSwap] =
useState<checkout.Widget<typeof checkout.WidgetType.SWAP>>();
// Initialise widgets, create wallet widget
useEffect(() => {
(async () => {
const widgets = await checkoutSDK.widgets({
config: { theme: checkout.WidgetTheme.DARK },
});
const wallet = widgets.create(checkout.WidgetType.WALLET)
const swap = widgets.create(checkout.WidgetType.SWAP)
setWallet(wallet);
setSwap(swap);
})();
}, []);
// mount wallet widget and add event listeners
useEffect(() => {
if(!wallet || !swap) return;
wallet.mount("wallet");
wallet.addListener(checkout.WalletEventType.CLOSE_WIDGET, () => {
wallet.unmount();
});
// Add listener for orchestrating wallet with swap
wallet.addListener(checkout.OrchestrationEventType.REQUEST_SWAP, (data: checkout.RequestSwapEvent) => {
wallet.unmount();
swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
})
}, [wallet, swap])
return (
<>
<div id="wallet" />
<div id="swap" />
</>
);
}
<html>
<head>
<!-- Load the SDK from jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/sdk.js"></script>
</head>
<body>
<div id="wallet"></div>
<div id="swap"></div>
<script>
// Initialize Checkout SDK
var checkout;
(async function () {
checkout = new ImmutableCheckout.Checkout();
const widgets = await checkout.widgets({
config: { theme: ImmutableCheckout.WidgetTheme.DARK },
});
const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
const swap = widgets.create(ImmutableCheckout.WidgetType.SWAP);
wallet.mount('wallet');
wallet.addListener('request-swap', (data) => {
wallet.unmount();
swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
})
})();
</script>
</body>
</html>
Once the event is raised and listened to, the Swap widget will open with the selected token pre-populated for swap.