964927b597
* docs improvements and changes * updated module definition * modules + dml changes * fix build * fix vale error * fix lint errors * fixes to stripe docs * fix condition * fix condition * fix module defintion * fix checkout * disable UI action * change oas preview action * flatten provider module options * fix lint errors * add module link docs * pr comments fixes * fix vale error * change node engine version * links -> linkable * add note about database name * small fixes * link fixes * fix response code in api reference * added migrations step
121 lines
3.3 KiB
Plaintext
121 lines
3.3 KiB
Plaintext
import { Table } from "docs-ui"
|
||
|
||
export const metadata = {
|
||
title: `${pageNumber} Admin Widgets`,
|
||
}
|
||
|
||
# {metadata.title}
|
||
|
||
In this chapter, you’ll learn more about widgets and how to use them.
|
||
|
||
## What is an Admin Widget?
|
||
|
||
Admin widgets are React components you inject into predetermined injection zones in the Medusa Admin dashboard.
|
||
|
||
For example, you can add a widget on the order details page that shows payment details retrieved from Stripe.
|
||
|
||
---
|
||
|
||
## How to Create a Widget?
|
||
|
||
A widget is created in a file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component. The file must also export the widget’s configurations.
|
||
|
||
For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
|
||
|
||
export const widgetHighlights = [
|
||
["5", "ProductWidget", "The React component of the product widget."],
|
||
["15", "zone", "The zone to inject the widget to."]
|
||
]
|
||
|
||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
|
||
import { defineWidgetConfig } from "@medusajs/admin-shared"
|
||
import { Container, Heading } from "@medusajs/ui"
|
||
|
||
// The widget
|
||
const ProductWidget = () => {
|
||
return (
|
||
<Container>
|
||
<Heading level="h2">Product Widget</Heading>
|
||
</Container>
|
||
)
|
||
}
|
||
|
||
// The widget's configurations
|
||
export const config = defineWidgetConfig({
|
||
zone: "product.details.before",
|
||
})
|
||
|
||
export default ProductWidget
|
||
```
|
||
|
||
The widget only shows the heading `Product Widget`.
|
||
|
||
Use the `defineWidgetConfig` function imported from `@medusajs/admin-shared` to create and export the widget's configurations. It accepts as a parameter an object with the following property:
|
||
|
||
- `zone`: A string or an array of strings, each being the name of the zone to inject the widget into.
|
||
|
||
In the example above, the widget is injected at the top of a product’s details.
|
||
|
||
---
|
||
|
||
## Test the Widget
|
||
|
||
To test out the widget, start the Medusa application:
|
||
|
||
```bash npm2yarn
|
||
npm run dev
|
||
```
|
||
|
||
Then, open a product’s details page. You’ll find your custom widget at the top of the page.
|
||
|
||
---
|
||
|
||
## Detail Widget Props
|
||
|
||
Widgets that are injected into a details page (for example, `product.details.before`) receive a `data` prop, which is the main data of the details page (for example, the product object).
|
||
|
||
For example:
|
||
|
||
export const detailHighlights = [
|
||
["10", "data", "Receive the data as a prop."],
|
||
["11", "AdminProduct", "Pass the expected type of `data` as a type argument."],
|
||
["15", "data.title"]
|
||
]
|
||
|
||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
|
||
import { defineWidgetConfig } from "@medusajs/admin-shared"
|
||
import { Container, Heading } from "@medusajs/ui"
|
||
import {
|
||
DetailWidgetProps,
|
||
AdminProduct,
|
||
} from "@medusajs/types"
|
||
|
||
// The widget
|
||
const ProductWidget = ({
|
||
data,
|
||
}: DetailWidgetProps<AdminProduct>) => {
|
||
return (
|
||
<Container>
|
||
<Heading level="h2">
|
||
Product Widget {data.title}
|
||
</Heading>
|
||
</Container>
|
||
)
|
||
}
|
||
|
||
// The widget's configurations
|
||
export const config = defineWidgetConfig({
|
||
zone: "product.details.before",
|
||
})
|
||
|
||
export default ProductWidget
|
||
```
|
||
|
||
Notice that the type of the props is `DetailWidgetProps`, which accepts as a type argument the expected type of `data`.
|
||
|
||
---
|
||
|
||
## Injection Zone
|
||
|
||
Refer to [this reference](!resources!/admin-widget-injection-zones) for the full list of injection zones and their props.
|