docs: revise admin customization pages (#10297)
* docs: revise admin customization pages * small re-iteration
This commit is contained in:
Shahed Nasser
GitHub
@@ -1,3 +1,5 @@
|
||||
import { Prerequisites } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin UI Routes`,
|
||||
}
|
||||
@@ -8,15 +10,22 @@ In this chapter, you’ll learn how to create a UI route in the admin dashboard.
|
||||
|
||||
## What is a UI Route?
|
||||
|
||||
A UI route is a React Component that adds a new page to your admin dashboard. The UI Route can be shown in the sidebar or added as a nested page.
|
||||
The Medusa Admin dashboard is customizable, allowing you to add new pages, called UI routes. You create a UI route as a React component showing custom content that allow admin users to perform custom actions.
|
||||
|
||||
For example, you may add a new page to manage product reviews.
|
||||
For example, you can add a new page to show and manage product reviews, which aren't available natively in Medusa.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a UI Route?
|
||||
|
||||
A UI route is created in a file named `page.tsx` under the `src/admin/routes` directory. The file’s default export must be the UI route’s React component.
|
||||
<Prerequisites
|
||||
items={[{
|
||||
link: "/learn/installation",
|
||||
text: "Medusa application installed"
|
||||
}]}
|
||||
/>
|
||||
|
||||
You create a UI route in a `page.tsx` file under a sub-directory of `src/admin/routes` directory. The file's path relative to `src/admin/routes` determines its path in the dashboard. The file’s default export must be the UI route’s React component.
|
||||
|
||||
For example, create the file `src/admin/routes/custom/page.tsx` with the following content:
|
||||
|
||||
@@ -36,7 +45,9 @@ const CustomPage = () => {
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
The new page’s path is the file’s path relative to `src/admin/routes`. So, the above UI route is a new page added at the path `localhost:9000/app/custom`.
|
||||
You add a new route at `http://localhost:9000/app/custom`. The `CustomPage` component holds the page's content, which currently only shows a heading.
|
||||
|
||||
In the route, you use [Medusa UI](!ui!), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
|
||||
|
||||
<Note title="Important" type="warning">
|
||||
|
||||
@@ -44,9 +55,7 @@ The UI route component must be created as an arrow function.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Test the UI Route
|
||||
### Test the UI Route
|
||||
|
||||
To test the UI route, start the Medusa application:
|
||||
|
||||
@@ -54,15 +63,13 @@ To test the UI route, start the Medusa application:
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, after logging into the admin dashboard, open the page `localhost:9000/app/custom` to see your custom page.
|
||||
Then, after logging into the admin dashboard, open the page `http://localhost:9000/app/custom` to see your custom page.
|
||||
|
||||
---
|
||||
|
||||
## Show UI Route in the Sidebar
|
||||
|
||||
A UI route file can export a configuration object that indicates a new item must be added in the sidebar linking to the new UI route.
|
||||
|
||||
For example:
|
||||
To add a sidebar item for your custom UI route, export a configuration object in the UI route's file:
|
||||
|
||||
export const highlights = [
|
||||
["16", "label", "The label of the UI route's sidebar item."],
|
||||
@@ -138,9 +145,9 @@ Some caveats for nested UI routes in the sidebar:
|
||||
|
||||
## Create Settings Page
|
||||
|
||||
To create a page under the settings section of the admin dashboard, create the UI route file under the path `src/admin/routes/settings`.
|
||||
To create a page under the settings section of the admin dashboard, create a UI route under the path `src/admin/routes/settings`.
|
||||
|
||||
For example:
|
||||
For example, create a UI route at `src/admin/routes/settings/custom/page.tsx`:
|
||||
|
||||
```tsx title="src/admin/routes/settings/custom/page.tsx"
|
||||
import { defineRouteConfig } from "@medusajs/admin-sdk"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { Table } from "docs-ui"
|
||||
import { Prerequisites } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin Widgets`,
|
||||
@@ -10,15 +10,22 @@ 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.
|
||||
The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
|
||||
|
||||
For example, you can add a widget on the order details page that shows payment details retrieved from Stripe.
|
||||
For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
<Prerequisites
|
||||
items={[{
|
||||
link: "/learn/installation",
|
||||
text: "Medusa application installed"
|
||||
}]}
|
||||
/>
|
||||
|
||||
You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
|
||||
|
||||
For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
|
||||
|
||||
@@ -50,11 +57,9 @@ export const config = defineWidgetConfig({
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
The widget only shows the heading `Product Widget`.
|
||||
You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](!ui!), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
|
||||
|
||||
Use the `defineWidgetConfig` function imported from `@medusajs/admin-sdk` 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.
|
||||
To export the widget's configurations, you use the `defineWidgetConfig` function imported from `@medusajs/admin-sdk`. It accepts as a parameter an object with the `zone` property, whose value is 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.
|
||||
|
||||
@@ -64,9 +69,7 @@ The widget component must be created as an arrow function.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Test the Widget
|
||||
### Test the Widget
|
||||
|
||||
To test out the widget, start the Medusa application:
|
||||
|
||||
@@ -78,11 +81,11 @@ Then, open a product’s details page. You’ll find your custom widget at the t
|
||||
|
||||
---
|
||||
|
||||
## Detail Widget Props
|
||||
## Props Passed in Detail Pages
|
||||
|
||||
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).
|
||||
Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
|
||||
|
||||
For example:
|
||||
For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
|
||||
|
||||
export const detailHighlights = [
|
||||
["10", "data", "Receive the data as a prop."],
|
||||
@@ -121,10 +124,16 @@ export const config = defineWidgetConfig({
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
Notice that the type of the props is `DetailWidgetProps`, which accepts as a type argument the expected type of `data`.
|
||||
The props type is `DetailWidgetProps`, and it accepts as a type argument the expected type of `data`. For the product details page, it's `AdminProduct`.
|
||||
|
||||
---
|
||||
|
||||
## Injection Zone
|
||||
|
||||
Refer to [this reference](!resources!/admin-widget-injection-zones) for the full list of injection zones and their props.
|
||||
|
||||
---
|
||||
|
||||
## Admin Components List
|
||||
|
||||
To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](!resources!/admin-components) to find common components.
|
||||
|
||||
@@ -84,7 +84,7 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
Your module's service extends a class returned by the `MedusaService` utility function. The `MedusaService` function accepts an object of data models, and returns a class with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on those data models.
|
||||
Your module's service extends a class returned by the `MedusaService` utility function. The `MedusaService` function accepts an object of data models, and returns a class with generated methods for data-management Create, Read, Update, and Delete (CRUD) operations on those data models. You can pass all data models in your module in this object.
|
||||
|
||||
For example, the `BlogModuleService` now has a `createPosts` method to create post records, and a `retrievePost` method to retrieve a post record. The suffix of each method (except for `retrieve`) is the pluralized name of the data model.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user