Skip to content

Commit

Permalink
docs(widget): widget events docs (#339)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shoom3301
shoom3301 authored Mar 21, 2024
1 parent b4c6874 commit e3920fe
Showing 1 changed file with 58 additions and 18 deletions.
76 changes: 58 additions & 18 deletions docs/cow-protocol/tutorials/widget.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Integrate the power of `CoW Swap` into your product!
With the widget, you can create an incredible trading interface. Specify the required pair of currencies, customize the
look and much more!

Create your own widget using the configurator https://widget.cow.fi
Create your own widget using the configurator https://widget.cow.fi.

![Demo](/img/tutorials/widget.png)

Expand Down Expand Up @@ -121,22 +121,24 @@ cowSwapWidget(

> All params are optional
| Parameter | Type | Default | Description |
|-----------------------|--------------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `width` | `string` | 400px | The width of the widget in css values (px, vh, etc.). |
| `height` | `string` | 600px | The height of the widget in css values (px, vh, etc.). |
| `appCode` | `string` | --- | The unique identifier of the widget consumer. Please fill the for to let us know a little about you: https://cowprotocol.typeform.com/to/rONXaxHV |
| `provider` | `EthereumProvider` | --- | The Ethereum provider to be used for interacting with a wallet. To connect, for example, to Rabby Wallet or Metamask, just set `window.ethereum`. You also might like to use https://web3modal.com |
| `chainId` | `number` | 1 | The blockchain ID on which the trade will take place. Currently supported: 1 (Mainnet), 5 (Goerli), 100 (Gnosis chain) |
| `tradeType` | `TradeType` | 'swap' | The type of trade. Can be `swap` or `limit` or `advanced`. |
| `env` | `CowSwapWidgetEnv` | 'prod' | The environment of the widget (`local` , `prod` , `dev` , `pr`). See [`COWSWAP_URLS`](https://github.com/cowprotocol/cowswap/blob/develop/libs/widget-lib/src/consts.ts) const value for urls. |
| `tradeAssets` | `TradeAssets` | Same as in swap.cow.fi | An object containing information about the selling and buying assets. Example: `{ asset: 'WBTC', amount: 12 }` or `{ asset: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' }` |
| `theme` | `CowSwapTheme` | 'light' | The theme of the widget (`'dark'` for dark theme or `'light'` for light theme). It is also possible to set your own colors (`CowSwapWidgetPalette`). See [Custom theme](#custom-theme) section for more details. |
| `logoUrl` | `string` | --- | Allows to set a custom logo for the widget. |
| `hideLogo` | `boolean` | false | Option to hide the logo in the widget. |
| `hideNetworkSelector` | `boolean` | false | Disables an opportunity to change the network from the widget UI. |
| `enabledTradeTypes` | `Array<TradeType>` | All are enabled | CoW Swap provides three trading widgets: `swap`, `limit` and `advanced` orders. Using this option you can narrow down the list of available trading widgets. |
| `partnerFee` | `PartnerFee` | --- | You can enable a fee for all trades in the widget. See [Partner fee](#partner-fee) section for more details. |
| Parameter | Type | Default | Description |
|------------------------|--------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `width` | `string` | 400px | The width of the widget in css values (px, vh, etc.). |
| `height` | `string` | 600px | The height of the widget in css values (px, vh, etc.). |
| `appCode` | `string` | --- | The unique identifier of the widget consumer. Please fill the for to let us know a little about you: https://cowprotocol.typeform.com/to/rONXaxHV. |
| `provider` | `EthereumProvider` | --- | The Ethereum provider to be used for interacting with a wallet. To connect, for example, to Rabby Wallet or Metamask, just set `window.ethereum`. You also might like to use https://web3modal.com. |
| `chainId` | `number` | 1 | The blockchain ID on which the trade will take place. Currently supported: 1 (Mainnet), 11155111 (Sepolia), 100 (Gnosis chain). |
| `tradeType` | `TradeType` | 'swap' | The type of trade. Can be `swap` or `limit` or `advanced`. |
| `env` | `CowSwapWidgetEnv` | 'prod' | The environment of the widget (`local` , `prod` , `dev` , `pr`). See [`COWSWAP_URLS`](https://github.com/cowprotocol/cowswap/blob/develop/libs/widget-lib/src/consts.ts) const value for urls. |
| `tradeAssets` | `TradeAssets` | Same as in swap.cow.fi | An object containing information about the selling and buying assets. Example: `{ asset: 'WBTC', amount: 12 }` or `{ asset: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' }`. |
| `theme` | `CowSwapTheme` | 'light' | The theme of the widget (`'dark'` for dark theme or `'light'` for light theme). It is also possible to set your own colors (`CowSwapWidgetPalette`). See [Custom theme](#custom-theme) section for more details. |
| `logoUrl` | `string` | --- | Allows to set a custom logo for the widget. |
| `disableToastMessages` | `boolean` | false | CoW Swap displays a pop-up notification when certain events occur, for example: an order has been filled. You may want to handle these events yourself and disable the display of notifications in the widget, to do this you need to enable this option. See [Events handling](#events-handling) section for more details. |
| `standaloneMode` | `boolean` | false | When this option is enabled, the widget will use its own Ethereum provider and the user will be able to connect a wallet from within the widget. |
| `hideLogo` | `boolean` | false | Option to hide the logo in the widget. |
| `hideNetworkSelector` | `boolean` | false | Disables an opportunity to change the network from the widget UI. |
| `enabledTradeTypes` | `Array<TradeType>` | All are enabled | CoW Swap provides three trading widgets: `swap`, `limit` and `advanced` orders. Using this option you can narrow down the list of available trading widgets. |
| `partnerFee` | `PartnerFee` | --- | You can enable a fee for all trades in the widget. See [Partner fee](#partner-fee) section for more details. |

## Custom theme

Expand Down Expand Up @@ -171,10 +173,48 @@ const params: CowSwapWidgetParams = {
cowSwapWidget(widgetContainer, params)
```

Try it yourself: https://widget.cow.fi
Try it yourself: https://widget.cow.fi.

![Custom theme](/img/tutorials/custom-theme.png)

## Events handling

The widget provides a bus of events that occur in the widget.
Using it, you can receive notifications, for example, when an order has been executed or when an approval transaction has been mined.

Separately, it is worth noting the `ON_TOAST_MESSAGE` event; it occurs every time any notification is displayed in CoW Swap.
To avoid double display of notifications, enable the `disableToastMessages` option in the widget configurations.

> A list of all possible events can be found in the source code on [Github](https://github.com/cowprotocol/cowswap/blob/develop/libs/events/src/types/events.ts).
### Events usage example

```typescript
import {cowSwapWidget, CowSwapWidgetParams, CowEventListeners, CowEvents} from '@cowprotocol/widget-lib'

const params: CowSwapWidgetParams = {
appCode: 'YOUR_APP_ID'
}

const listeners: CowEventListeners = [
{
event: CowEvents.ON_TOAST_MESSAGE,
handler: (event) => console.log('[ON_TOAST_MESSAGE]', event.message)
},
{
event: CowEvents.ON_EXPIRED_ORDER,
handler: (event) => console.log('Order was expired:', event.order)
},
]

const { updateListeners } = cowSwapWidget(container, { params, listeners })

// If you want to change listeners at some point, you can do it like:
updateListeners([{
event: CowEvents.ON_CANCELLED_ORDER,
handler: (event) => console.log('Order was cancelled:', event.order)
}])
```

## Widget updating

Expand Down

0 comments on commit e3920fe

Please sign in to comment.