chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser
File diff suppressed because one or more lines are too long
@@ -0,0 +1,27 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin Development`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Admin customizations are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
In the next chapters, you'll learn more about possible admin customizations.
|
||||
|
||||
You can customize the admin dashboard by:
|
||||
|
||||
- Adding new sections to existing pages using Widgets.
|
||||
- Adding new pages using UI Routes.
|
||||
- Adding new pages to the Settings section of the admin dashboard using Setting Pages.
|
||||
|
||||
---
|
||||
|
||||
## Medusa UI Package
|
||||
|
||||
Medusa provides a Medusa UI package to facilitate your admin development through ready-made components and ensure a consistent design between your customizations and the dashboard’s design.
|
||||
|
||||
Refer to the [Medusa UI documentation](https://docs.medusajs.com/ui) to learn how to install it and use its components.
|
||||
@@ -0,0 +1,152 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin Setting Pages`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Admin customizations are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
In this chapter, you’ll learn how to create a setting page in the admin dashboard.
|
||||
|
||||
## What is a Setting Page?
|
||||
|
||||
A setting page is a React component that adds a new page to the settings panel of the admin dashboard.
|
||||
|
||||
For example, you may create a setting page to manage configurations related to your custom functionalities.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Setting Page?
|
||||
|
||||
A setting page is created in a file named `page.tsx` under the `src/admin/settings` directory. The file’s default export must be the React component, and it must also export a configuration object.
|
||||
|
||||
For example, you can create the file `src/admin/settings/custom/page.tsx` with the following content:
|
||||
|
||||
```tsx title="src/admin/settings/custom/page.tsx"
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import { ChatBubbleLeftRight } from "@medusajs/icons"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
return (
|
||||
<div>
|
||||
<h1>Custom Setting Page</h1>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
// optional
|
||||
icon: ChatBubbleLeftRight,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
The new setting page’s path is the file’s path relative to `src/admin/settings` and prefixed with `/a/settings`. So, the above UI route is a new page added at the path `localhost:7001/a/settings/custom`.
|
||||
|
||||
The setting page is shown on the Settings panel as a card. In the exported configuration object, you configure the card’s label, description, and optionally icon. In this example, you use an icon from [Medusa’s UI Icons package](https://docs.medusajs.com/ui/icons/overview).
|
||||
|
||||
### Test the Setting Page
|
||||
|
||||
To test the setting page, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, open the Settings page of the admin dashboard. You’ll find a new card that links to your setting page.
|
||||
|
||||
---
|
||||
|
||||
## Using UI Components
|
||||
|
||||
Similar to other admin customizations, it’s highly recommended that you use the [Medusa UI package](https://docs.medusajs.com/ui) to match your page’s design with the rest of the Medusa Admin.
|
||||
|
||||
For example, you can rewrite the above UI route to the following:
|
||||
|
||||
```tsx title="src/admin/settings/custom/page.tsx"
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import { ChatBubbleLeftRight } from "@medusajs/icons"
|
||||
import { Container, Heading } from "@medusajs/ui"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
return (
|
||||
<Container>
|
||||
<Heading level="h1">Custom Setting Page</Heading>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
icon: ChatBubbleLeftRight,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setting Page Props
|
||||
|
||||
A setting page receives a `notify` prop, which is an object having the following properties:
|
||||
|
||||
- `success`: a function that shows a success toast message.
|
||||
- `error`: a function that shows an error toast message.
|
||||
- `warn`: a function that shows a warning toast message.
|
||||
- `info`: a function that shows an info toast message.
|
||||
|
||||
Each of these functions accepts two parameters: the message’s title and the message’s content.
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title="src/admin/settings/custom/page.tsx" highlights={[["11", "success", "Show a success toast message on the click of a button."]]}
|
||||
import type { RouteProps, SettingConfig } from "@medusajs/admin"
|
||||
import { ChatBubbleLeftRight } from "@medusajs/icons"
|
||||
import { Container, Heading, Button } from "@medusajs/ui"
|
||||
|
||||
const CustomSettingPage = ({ notify }: RouteProps) => {
|
||||
return (
|
||||
<Container>
|
||||
<Heading level="h1">Custom Setting Page</Heading>
|
||||
<Button
|
||||
onClick={() =>
|
||||
notify.success("Success!", "You clicked the button!")
|
||||
}
|
||||
className="mt-3"
|
||||
>
|
||||
Click me
|
||||
</Button>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
icon: ChatBubbleLeftRight,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
If you click the button on your setting page, a toast message will show with the title and message you specified.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Admin UI Routes support [Tailwind CSS](https://tailwindcss.com/) out of the box.
|
||||
|
||||
</Note>
|
||||
@@ -0,0 +1,72 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin Development Tips`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Admin customizations are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
In this chapter, you'll find some tips for your admin development.
|
||||
|
||||
## Sending Requests to API Routes
|
||||
|
||||
To send requests to your API routes in your admin customizations, it’s highly recommended to use the Medusa React or Medusa JS Client packages.
|
||||
|
||||
Check out their references for more details on available hooks or methods and how to use them.
|
||||
|
||||
---
|
||||
|
||||
## Routing Functionalities
|
||||
|
||||
To navigate or link to other pages, or use other routing functionalities, use the [react-router-dom](https://reactrouter.com/en/main) package:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install react-router-dom
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={[["18", "Link", "Add a link to another page."]]}
|
||||
import type {
|
||||
WidgetConfig,
|
||||
ProductDetailsWidgetProps,
|
||||
} from "@medusajs/admin"
|
||||
import { Container, Heading, Button } from "@medusajs/ui"
|
||||
import { Link } from "react-router-dom"
|
||||
|
||||
// The widget
|
||||
const ProductWidget = ({
|
||||
product,
|
||||
}: ProductDetailsWidgetProps) => {
|
||||
return (
|
||||
<Container>
|
||||
<Heading level="h2">
|
||||
Product Widget {product.title}
|
||||
</Heading>
|
||||
<Button className="mt-3" variant="transparent">
|
||||
<Link to={"/a/orders"}>View Orders</Link>
|
||||
</Button>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
// The widget's configurations
|
||||
export const config: WidgetConfig = {
|
||||
zone: "product.details.after",
|
||||
}
|
||||
|
||||
export default ProductWidget
|
||||
|
||||
```
|
||||
|
||||
This adds a widget in a product's details page with a link to the Orders page.
|
||||
|
||||
<Note title="Learn more">
|
||||
|
||||
Refer to [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
|
||||
|
||||
</Note>
|
||||
@@ -0,0 +1,182 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin UI Routes`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Admin customizations are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
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 custom new page to your admin dashboard. The UI Route can be shown in the sidebar or added as a nested page.
|
||||
|
||||
For example, you may add a new page to manage product reviews.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
For example, create the file `src/admin/routes/custom/page.tsx` with the following content:
|
||||
|
||||
```tsx title="src/admin/routes/custom/page.tsx"
|
||||
const CustomPage = () => {
|
||||
return <div>This is my custom route</div>
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
The new page’s path is the file’s path relative to `src/admin/routes` and prefixed with `/a`. So, the above UI route is a new page added at the path `localhost:7001/a/custom`.
|
||||
|
||||
### Test the UI Route
|
||||
|
||||
To test the UI route, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, after logging into the admin dashboard, open the page `localhost:7001/a/custom` to see your custom page.
|
||||
|
||||
---
|
||||
|
||||
## Using UI Components
|
||||
|
||||
Similar to Widgets, it’s highly recommended that you use the [Medusa UI package](https://docs.medusajs.com/ui) to match your page’s design with the rest of the Medusa Admin.
|
||||
|
||||
For example, you can rewrite the above UI route to the following:
|
||||
|
||||
```tsx title="src/admin/routes/custom/page.tsx"
|
||||
import { Container } from "@medusajs/ui"
|
||||
|
||||
const CustomPage = () => {
|
||||
return <Container>This is my custom route</Container>
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UI Route Props
|
||||
|
||||
A UI Route receives a `notify` prop, which is an object having the following properties:
|
||||
|
||||
- `success`: a function that shows a success toast message.
|
||||
- `error`: a function that shows an error toast message.
|
||||
- `warn`: a function that shows a warning toast message.
|
||||
- `info`: a function that shows an info toast message.
|
||||
|
||||
Each of these functions accepts two parameters: the message’s title and the message’s content.
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title="src/admin/routes/custom/page.tsx" highlights={[["10", "success", "Show a success toast message on the click of a button."]]}
|
||||
import { RouteProps } from "@medusajs/admin"
|
||||
import { Container, Text, Button } from "@medusajs/ui"
|
||||
|
||||
const CustomPage = ({ notify }: RouteProps) => {
|
||||
return (
|
||||
<Container>
|
||||
<Text>This is my custom route</Text>
|
||||
<Button
|
||||
onClick={() =>
|
||||
notify.success("Success!", "You clicked the button!")
|
||||
}
|
||||
className="mt-3"
|
||||
>
|
||||
Click me
|
||||
</Button>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Admin UI Routes support [Tailwind CSS](https://tailwindcss.com/) out of the box.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
The configuration object has the property `link`, which is an object having the following properties:
|
||||
|
||||
- `label`: the new sidebar item’s label.
|
||||
- `icon`: an optional React component that acts as an icon in the sidebar. If not provided, a default icon is used.
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title="src/admin/routes/custom/page.tsx" highlights={[["21"], ["22"], ["23"], ["24"], ["25"], ["26"]]}
|
||||
import { RouteConfig, RouteProps } from "@medusajs/admin"
|
||||
import { Container, Text, Button } from "@medusajs/ui"
|
||||
import { ChatBubbleLeftRight } from "@medusajs/icons"
|
||||
|
||||
const CustomPage = ({ notify }: RouteProps) => {
|
||||
return (
|
||||
<Container>
|
||||
<Text>This is my custom route</Text>
|
||||
<Button
|
||||
onClick={() =>
|
||||
notify.success("Success!", "You clicked the button!")
|
||||
}
|
||||
className="mt-3"
|
||||
>
|
||||
Click me
|
||||
</Button>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: RouteConfig = {
|
||||
link: {
|
||||
label: "Custom Route",
|
||||
icon: ChatBubbleLeftRight,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
This adds a new sidebar item with the label `Custom Route` and an icon from the [Medusa UI Icons package](https://docs.medusajs.com/ui/icons/overview).
|
||||
|
||||
---
|
||||
|
||||
## Path Parameters
|
||||
|
||||
A UI route can accept path parameters if the name of any of the directories in its path is of the format `[param]`. For example, `src/admin/routes/custom/[id]/page.tsx`.
|
||||
|
||||
To retrieve the path parameters, install the `react-router-dom` to use its `useParams` hook:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install react-router-dom
|
||||
```
|
||||
|
||||
For example, create the file `src/admin/routes/custom/[id]/page.tsx` with the following content:
|
||||
|
||||
```tsx title="src/admin/routes/custom/[id]/page.tsx" highlights={[["5", "", "Retrieve the path parameter."], ["7", "{id}", "Show the path parameter."]]}
|
||||
import { useParams } from "react-router-dom"
|
||||
import { Container } from "@medusajs/ui"
|
||||
|
||||
const CustomPage = () => {
|
||||
const { id } = useParams()
|
||||
|
||||
return <Container>Passed ID: {id}</Container>
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
@@ -0,0 +1,160 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Admin Widgets`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Admin customizations are coming soon.
|
||||
|
||||
</Note>
|
||||
|
||||
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, and must also export the widget’s configurations.
|
||||
|
||||
For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
|
||||
|
||||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={[["4", "ProductWidget", "The React component of the product widget."], ["14", "", "The zone to inject the widget to."]]}
|
||||
import type { WidgetConfig } from "@medusajs/admin"
|
||||
|
||||
// The widget
|
||||
const ProductWidget = () => {
|
||||
return (
|
||||
<div>
|
||||
<h2>Product Widget</h2>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// The widget's configurations
|
||||
export const config: WidgetConfig = {
|
||||
zone: "product.details.after",
|
||||
}
|
||||
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
The widget only shows the heading `Product Widget`.
|
||||
|
||||
In the exported widget’s configurations, you must specify the zone to inject the widget into. The `zone` property can be a string or an array of strings, each being the name of the injection zone.
|
||||
|
||||
In the example above, the widget is injected after 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 bottom of the page.
|
||||
|
||||
---
|
||||
|
||||
## Using UI Components
|
||||
|
||||
It’s highly recommended that you use the [Medusa UI package](https://docs.medusajs.com/ui) to match your widget’s design with the rest of the Medusa Admin.
|
||||
|
||||
For example, you can rewrite the above component to the following:
|
||||
|
||||
```tsx title="src/admin/widgets/product-widget.tsx"
|
||||
import type { WidgetConfig } from "@medusajs/admin"
|
||||
import { Container, Heading } from "@medusajs/ui"
|
||||
|
||||
const ProductWidget = () => {
|
||||
return (
|
||||
<Container>
|
||||
<Heading level="h2">Product Widget</Heading>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: WidgetConfig = {
|
||||
zone: "product.details.after",
|
||||
}
|
||||
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Widget Props
|
||||
|
||||
A widget receives a `notify` prop, which is an object having the following properties:
|
||||
|
||||
- `success`: a function that shows a success toast message.
|
||||
- `error`: a function that shows an error toast message.
|
||||
- `warn`: a function that shows a warning toast message.
|
||||
- `info`: a function that shows an info toast message.
|
||||
|
||||
Each of these functions accepts two parameters: the message’s title, and the message’s content.
|
||||
|
||||
In addition, some injection zones provide additional props based on the page’s context.
|
||||
|
||||
For example, you can rewrite the above widget to the following:
|
||||
|
||||
```tsx title="src/admin/widgets/product-widget.tsx" highlights={[["14", "product.title", "Show the product's title."], ["18", "success", "Show a success toast message on the click of a button."]]}
|
||||
import type {
|
||||
WidgetConfig,
|
||||
ProductDetailsWidgetProps,
|
||||
} from "@medusajs/admin"
|
||||
import { Container, Heading, Button } from "@medusajs/ui"
|
||||
|
||||
const ProductWidget = ({
|
||||
notify,
|
||||
product,
|
||||
}: ProductDetailsWidgetProps) => {
|
||||
return (
|
||||
<Container>
|
||||
<Heading level="h2">
|
||||
Product Widget {product.title}
|
||||
</Heading>
|
||||
<Button
|
||||
onClick={() =>
|
||||
notify.success("Success!", "You clicked the button!")
|
||||
}
|
||||
className="mt-3"
|
||||
>
|
||||
Click me
|
||||
</Button>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: WidgetConfig = {
|
||||
zone: "product.details.after",
|
||||
}
|
||||
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
Since the widget is in the product’s details page, it receives the product as a prop. The widget now shows the title of the product in the header.
|
||||
|
||||
It also shows a button that, when you click, shows a success toast message.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Admin Widgets support [Tailwind CSS](https://tailwindcss.com/) out of the box.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Injection Zone
|
||||
|
||||
Refer to [this reference](!resources!/admin-widget-injection-zones) for the full list of injection zones and their props.
|
||||
Reference in New Issue
Block a user