From e936d578251afffc0055a159c4a4648461666a20 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 6 Dec 2024 16:34:02 +0200 Subject: [PATCH] docs: revise admin customization pages (#10466) * docs: revise admin customization pages * fix prerequisites link * apply lint --- .../data-models/check-constraints/page.mdx | 12 +- .../data-models/relationships/page.mdx | 2 +- .../workflows/compensation-function/page.mdx | 2 +- .../custom-features/api-route/page.mdx | 2 +- .../customization/customize-admin/page.mdx | 21 +- .../customize-admin/route/page.mdx | 486 ++++++++++++++---- .../customize-admin/widget/page.mdx | 169 ++++-- www/apps/book/generated/edit-dates.mjs | 6 +- www/apps/book/sidebar.mjs | 2 +- 9 files changed, 538 insertions(+), 164 deletions(-) diff --git a/www/apps/book/app/learn/advanced-development/data-models/check-constraints/page.mdx b/www/apps/book/app/learn/advanced-development/data-models/check-constraints/page.mdx index 59c11996e6349..fc6b1dd15df64 100644 --- a/www/apps/book/app/learn/advanced-development/data-models/check-constraints/page.mdx +++ b/www/apps/book/app/learn/advanced-development/data-models/check-constraints/page.mdx @@ -29,12 +29,12 @@ export const checks1Highlights = [ ```ts highlights={checks1Highlights} import { model } from "@medusajs/framework/utils" -const CustomProduct = model.define('custom_product', { +const CustomProduct = model.define("custom_product", { // ... price: model.bigNumber(), }) .checks([ - (columns) => `${columns.price} >= 0` + (columns) => `${columns.price} >= 0`, ]) ``` @@ -53,15 +53,15 @@ export const checks2Highlights = [ ```ts highlights={checks2Highlights} import { model } from "@medusajs/framework/utils" -const CustomProduct = model.define('custom_product', { +const CustomProduct = model.define("custom_product", { // ... price: model.bigNumber(), }) .checks([ { - name: 'custom_product_price_check', - expression: (columns) => `${columns.price} >= 0` - } + name: "custom_product_price_check", + expression: (columns) => `${columns.price} >= 0`, + }, ]) ``` diff --git a/www/apps/book/app/learn/advanced-development/data-models/relationships/page.mdx b/www/apps/book/app/learn/advanced-development/data-models/relationships/page.mdx index 8ecc950a274bc..fcd5366ae2805 100644 --- a/www/apps/book/app/learn/advanced-development/data-models/relationships/page.mdx +++ b/www/apps/book/app/learn/advanced-development/data-models/relationships/page.mdx @@ -152,7 +152,7 @@ const Order = model.define("order", { mappedBy: "orders", pivotTable: "order_product", joinColumn: "order_id", - inverseJoinColumn: "product_id" + inverseJoinColumn: "product_id", }), }) diff --git a/www/apps/book/app/learn/advanced-development/workflows/compensation-function/page.mdx b/www/apps/book/app/learn/advanced-development/workflows/compensation-function/page.mdx index 0dd06ce533aa0..ce4e551d349c0 100644 --- a/www/apps/book/app/learn/advanced-development/workflows/compensation-function/page.mdx +++ b/www/apps/book/app/learn/advanced-development/workflows/compensation-function/page.mdx @@ -236,7 +236,7 @@ const step1 = createStep( ) return new StepResponse(ids, prevData) - }, + } ) ``` diff --git a/www/apps/book/app/learn/customization/custom-features/api-route/page.mdx b/www/apps/book/app/learn/customization/custom-features/api-route/page.mdx index f4d424556be2e..979a0e5a962d4 100644 --- a/www/apps/book/app/learn/customization/custom-features/api-route/page.mdx +++ b/www/apps/book/app/learn/customization/custom-features/api-route/page.mdx @@ -97,7 +97,7 @@ You create a validation schema in a TypeScript or JavaScript file under a sub-di import { z } from "zod" export const PostAdminCreateBrand = z.object({ - name: z.string() + name: z.string(), }) ``` diff --git a/www/apps/book/app/learn/customization/customize-admin/page.mdx b/www/apps/book/app/learn/customization/customize-admin/page.mdx index e23488a45388f..806a4c78e4c9b 100644 --- a/www/apps/book/app/learn/customization/customize-admin/page.mdx +++ b/www/apps/book/app/learn/customization/customize-admin/page.mdx @@ -1,10 +1,23 @@ export const metadata = { - title: `${pageNumber} Customize Admin to Add Brands`, + title: `${pageNumber} Customize Medusa Admin Dashboard`, } # {metadata.title} -In the next chapters, you'll continue with the brands example to learn how to customize the Medusa Admin to: +In the previous chapters, you've customized your Medusa application to [add brands](../custom-features/module/page.mdx), [expose an API route to create brands](../custom-features/api-route/page.mdx), and [linked brands to products](../extend-features/define-link/page.mdx). -- Show a product's brand on its details page using a widget. -- Add a page showing the list of brands in your application using a UI route. +After customizing and extending your application with new features, you may need to provide an interface for admin users to utilize these features. The Medusa Admin dashboard is extendable, allowing you to: + +- Insert components, called [widgets](../../advanced-development/admin/widgets/page.mdx), on existing pages. +- Add new pages, called [UI Routes](../../advanced-development/admin/ui-routes/page.mdx). + +From these customizations, you can send requests to custom API routes, allowing admin users to manage custom resources on the dashboard + +--- + +## Next Chapters: View Brands in Dashboard + +In the next chapters, you'll continue with the brands example to: + +- Add a new section to the product details page that shows the product's brand. +- Add a new page in the dashboard that shows all brands in the store. diff --git a/www/apps/book/app/learn/customization/customize-admin/route/page.mdx b/www/apps/book/app/learn/customization/customize-admin/route/page.mdx index 049cb0b6edb96..37b5eacc96b94 100644 --- a/www/apps/book/app/learn/customization/customize-admin/route/page.mdx +++ b/www/apps/book/app/learn/customization/customize-admin/route/page.mdx @@ -1,196 +1,480 @@ import { Prerequisites } from "docs-ui" export const metadata = { - title: `${pageNumber} Create Brands List UI Route in Admin`, + title: `${pageNumber} Create Brands UI Route in Admin`, } # {metadata.title} - - -This chapter covers how to create a UI route (or page) that shows your brands as a step of the ["Customize Admin" chapter](../page.mdx). - - - -## 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. - ---- - -## Prerequisite: Add Retrieve Brand API Route +In this chapter, you'll add a UI route to the admin dashboard that shows the all [brands](../../custom-features/module/page.mdx) in a new page. You'll retrieve the brands from the server and display them in a table with pagination. -Before adding the UI route, you need an API route that retrieves all brands. +## 1. Get Brands API Route + +In a [previous chapter](../../extend-features/query-linked-records/page.mdx), you learned how to add an API route that retrieves brands and their products using [Query](../../../advanced-development/module-links/query/page.mdx). You'll expand that API route to support pagination, so that on the admin dashboard you can show the brands in a paginated table. -Create the file `src/api/admin/brands/route.ts` with the following content: +Replace or create the `GET` API route at `src/api/admin/brands/route.ts` with the following: + +export const apiRouteHighlights = [ + ["15", "metadata", "Pagination details, such as the total count or how many items were skipped."], + ["18", "remoteQueryConfig", "Query configurations parsed from the request."], +] -```ts title="src/api/admin/brands/route.ts" collapsibleLines="1-7" expandMoreButton="Show Imports" +```ts title="src/api/admin/brands/route.ts" highlights={apiRouteHighlights} +// other imports... import { MedusaRequest, MedusaResponse, } from "@medusajs/framework/http" -import { BRAND_MODULE } from "../../../modules/brand" -import BrandModuleService from "../../../modules/brand/service" export const GET = async ( req: MedusaRequest, res: MedusaResponse ) => { - const brandModuleService: BrandModuleService = req.scope.resolve( - BRAND_MODULE - ) - - const limit = req.query.limit || 15 - const offset = req.query.offset || 0 - - const [brands, count] = await brandModuleService.listAndCountBrands({}, { - skip: offset as number, - take: limit as number, + const query = req.scope.resolve("query") + + const { + data: brands, + metadata: { count, take, skip }, + } = await query.graph({ + entity: "brand", + ...req.remoteQueryConfig, }) - res.json({ + res.json({ brands, count, - limit, - offset, + limit: take, + offset: skip, }) } ``` -This adds a `GET` API route at `/admin/brands`. +In the API route, you use Query's `graph` method to retrieve the brands. In the method's object parameter, you spread the `remoteQueryConfig` property of the request object. This property holds configurations for pagination and retrieved fields. + +The query configurations are combined from default configurations, which you'll add next, and the request's query parameters: + +- `fields`: The fields to retrieve in the brands. +- `limit`: The maximum number of items to retrieve. +- `offset`: The number of items to skip before retrieving the returned items. + +When you pass pagination configurations to the `graph` method, the returned object has the pagination's details in a `metadata` property, whose value is an object having the following properties: + +- `count`: The total count of items. +- `take`: The maximum number of items returned in the `data` array. +- `skip`: The number of items skipped before retrieving the returned items. + +You return in the response the retrieved brands and the pagination configurations. + + + +Learn more about pagination with Query in [this chapter](../../../advanced-development/module-links/query/page.mdx#apply-pagination). + + + +--- + +## 2. Add Default Query Configurations + +Next, you'll set the default query configurations of the above API route and allow passing query parameters to change the configurations. + +Medusa provides a `validateAndTransformQuery` middleware that validates the accepted query parameters for a request and sets the default Query configuration. So, in `src/api/middlewares.ts`, add a new middleware configuration object: + +```ts title="src/api/middlewares.ts" +import { + defineMiddlewares, + validateAndTransformQuery, +} from "@medusajs/framework/http" +import { createFindParams } from "@medusajs/medusa/api/utils/validators" +// other imports... + +export const GetBrandsSchema = createFindParams() + +export default defineMiddlewares({ + routes: [ + // ... + { + matcher: "/admin/brands", + method: "GET", + middlewares: [ + validateAndTransformQuery( + GetBrandsSchema, + { + defaults: [ + "id", + "name", + "products.*", + ], + isList: true, + } + ), + ], + }, + + ], +}) +``` + +You apply the `validateAndTransformQuery` middleware on the `GET /admin/brands` API route. The middleware accepts two parameters: -In the API route, you resolve the Brand Module's main service and use its `listAndCountBrands` method to retrieve the list of brands with their total count. +- A [Zod](https://zod.dev/) schema that a request's query parameters must satisfy. Medusa provides a `createFindParams` utility that generates a Zod schema with the following properties: + - `fields`: A comma-separated string indicating the fields to retrieve. + - `limit`: The maximum number of items to retrieve. + - `offset`: The number of items to skip before retrieving the returned items. + - `order`: The name of the field to sort the items by. Learn more about sorting in [the API reference](!api!/admin#sort-order) +- An object of Query configurations having the following properties: + - `defaults`: An array of default fields and relations to retrieve. + - `isList`: Whether the API route returns a list of items. -This method accepts as a first parameter filters to apply on the retrieved data, and as a second parameter configurations for pagination. +By applying the above middleware, you can pass pagination configurations to `GET /admin/brands`, which will return a paginated list of brands. You'll see how it works when you create the UI route. -Learn more about the `listAndCount` method and its parameters in [this reference](!resources!/service-factory-reference/methods/listAndCount). +Learn more about using the `validateAndTransformQuery` middleware to configure Query in [this chapter](../../../advanced-development/module-links/query/page.mdx#request-query-configurations). --- -## Add a UI Route to Show Brands +## 3. Initialize JS SDK + +In your custom UI route, you'll retrieve the brands by sending a request to the Medusa server. Medusa has a [JS SDK](!resources!/js-sdk) that simplifies sending requests to the core API route. + +If you didn't follow the [previous chapter](../widget/page.mdx), create the file `src/admin/lib/sdk.ts` with the following content: -A UI route is created in a file named `page.tsx` under subdirectories of the `src/admin/routes` directory. The file’s default export must be the UI route’s React component. +![The directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414606/Medusa%20Book/brands-admin-dir-overview-1_jleg0t.jpg) + +```ts title="src/admin/lib/sdk.ts" +import Medusa from "@medusajs/js-sdk" + +export const sdk = new Medusa({ + baseUrl: "http://localhost:9000", + debug: process.env.NODE_ENV === "development", + auth: { + type: "session", + }, +}) +``` -To create a UI route that shows the list of brands, create the file `src/admin/routes/brands/page.tsx` with the following content: +You initialize the SDK passing it the following options: + +- `baseUrl`: The URL to the Medusa server. +- `debug`: Whether to enable logging debug messages. This should only be enabled in development. +- `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard. + +You can now use the SDK to send requests to the Medusa server. + + + +Learn more about the JS SDK and its options in [this reference](!resources!/js-sdk). + + + +--- + +## 4. Add a UI Route to Show Brands + +You'll now add the UI route that shows the paginated list of brands. A UI route is a React component created in a `page.tsx` file under a sub-directory of `src/admin/routes`. The file's path relative to src/admin/routes determines its path in the dashboard. + + + +Learn more about UI routes in [this chapter](../../../advanced-development/admin/ui-routes/page.mdx). + + + +So, to add the UI route at the `localhost:9000/app/brands` path, create the file `src/admin/routes/brands/page.tsx` with the following content: + +![Directory structure of the Medusa application after adding the UI route.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733472011/Medusa%20Book/brands-admin-dir-overview-3_syytld.jpg) export const uiRouteHighlights = [ - ["7", "brands", "State variable to store the brands."], - ["12", "fetch", "Retrieve the brands from the custom API route."] + ["8", "BrandsPage", "The UI route that displays a new page."], + ["23", "defineRouteConfig", "Export config to add a link for the UI route in the sidebar."], + ["24", "label", "The sidebar item's label."], + ["25", "icon", "The sidebar item's icon."] ] ```tsx title="src/admin/routes/brands/page.tsx" highlights={uiRouteHighlights} -import { Table, Container, Heading } from "@medusajs/ui" -import { useEffect, useState } from "react" import { defineRouteConfig } from "@medusajs/admin-sdk" import { TagSolid } from "@medusajs/icons" +import { Container, Heading } from "@medusajs/ui" +import { useQuery } from "@tanstack/react-query" +import { sdk } from "../../lib/sdk" +import { useMemo, useState } from "react" const BrandsPage = () => { - const [brands, setBrands] = useState< - Record[] - >([]) - - useEffect(() => { - fetch(`/admin/brands`, { - credentials: "include", - }) - .then((res) => res.json()) - .then(({ brands: brandsData }) => { - setBrands(brandsData) - }) - }, []) - + // TODO retrieve brands return (
- Brands -
-
- - - - ID - Name - - - - {brands.map((brand) => ( - - {brand.id} - {brand.name} - - ))} - -
+
+ Brands +
+ {/* TODO show brands */} ) } +export const config = defineRouteConfig({ + label: "Brands", + icon: TagSolid, +}) + export default BrandsPage +``` + +A route's file must export the React component that will be rendered in the new page. It must be the default export of the file. You can also export configurations that add a link in the sidebar for the UI route. You create these configurations using `defineRouteConfig` from the Admin Extension SDK. + +So far, you only show a "Brands" header. In admin customizations, use components from the [Medusa UI package](!ui!) to maintain a consistent user interface and design in the dashboard. + +### Add Table Component -// TODO export configuration +To show the brands with pagination functionalities, you'll create a new `Table` component that uses the UI package's [Table](!ui!/components/table) component with some alterations to match the design of the Medusa Admin. This new component is taken from the [Admin Components guide](!resources!/admin-components/components/table). + +Create the `Table` component in the file `src/admin/components/table.tsx`: + +![Directory structure of the Medusa application after adding the table component.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733472527/Medusa%20Book/brands-admin-dir-overview-4_avosrf.jpg) + +```tsx title="src/admin/components/table.tsx" +import { useMemo } from "react" +import { Table as UiTable } from "@medusajs/ui" + +export type TableProps = { + columns: { + key: string + label?: string + render?: (value: unknown) => React.ReactNode + }[] + data: Record[] + pageSize: number + count: number + currentPage: number + setCurrentPage: (value: number) => void +} + +export const Table = ({ + columns, + data, + pageSize, + count, + currentPage, + setCurrentPage, +}: TableProps) => { + const pageCount = useMemo(() => { + return Math.ceil(count / pageSize) + }, [count, pageSize]) + + const canNextPage = useMemo(() => { + return currentPage < pageCount - 1 + }, [currentPage, pageCount]) + const canPreviousPage = useMemo(() => { + return currentPage - 1 >= 0 + }, [currentPage]) + + const nextPage = () => { + if (canNextPage) { + setCurrentPage(currentPage + 1) + } + } + + const previousPage = () => { + if (canPreviousPage) { + setCurrentPage(currentPage - 1) + } + } + + console.log(pageCount, canNextPage, canPreviousPage, currentPage) + + return ( +
+ + + + {columns.map((column, index) => ( + + {column.label || column.key} + + ))} + + + + {data.map((item, index) => { + const rowIndex = "id" in item ? item.id as string : index + return ( + + {columns.map((column, index) => ( + + <> + {column.render && column.render(item[column.key])} + {!column.render && ( + <>{item[column.key] as string} + )} + + + ))} + + ) + })} + + + +
+ ) +} ``` -This adds a new page in the admin at `http://localhost:9000/app/brands`. +This component accepts the following props: -In the UI route's component, you retrieve the brands from the `/admin/brands` API route. You show the brands in a table. +- `columns`: An array of the table's columns. +- `data`: The rows in the table. +- `pageSize`: The maximum number of items shown in a page. +- `count`: The total number of items. +- `currentPage`: A zero-based index of the current page. +- `setCurrentPage`: A function to change the current page. - +In the component, you use the UI package's [Table](!ui!/components/table) component to display the data received as a prop in a table that supports pagination. -Admin customizations can use the [Medusa UI package](!ui!) to align your customizations with the admin's design. Also, [this guide](!resources!/admin-components) includes examples of common components in the Medusa Admin. +You can learn more about this component's implementation and how it works in the [Admin Components guide](!resources!/admin-components), which provides more examples of how to build common components in the Medusa Admin dashboard. - +### Retrieve Brands From API Route -### Add UI Route to the Sidebar +You'll now update the UI route to retrieve the brands from the API route you added earlier. -To add the UI route to the sidebar, replace the `TODO` at the end of the file with the following: +First, add the following type in `src/admin/routes/brands/page.tsx`: -```ts title="src/admin/routes/brands/page.tsx" -export const config = defineRouteConfig({ - label: "Brands", - icon: TagSolid, +```tsx title="src/admin/routes/brands/page.tsx" +type BrandsResponse = { + brands: { + id: string + name: string + }[] + count: number + limit: number + offset: number +} +``` + +This is the type of expected response from the `GET /admin/brands` API route. + +Then, replace the `// TODO retrieve brands` in the component with the following: + +export const queryHighlights = [ + ["1", "currentPage", "A zero-based index of the current page of items."], + ["2", "limit", "The maximum number of items per page."], + ["3", "offset", "The number of items to skip before retrieving the page's items."], + ["7", "useQuery", "Retrieve brands using Tanstack Query"], + ["8", "fetch", "Send a request to a custom API route."], + ["8", "`/admin/brands`", "The API route's path."], + ["9", "query", "Query parameters to pass in the request"] +] + +```tsx title="src/admin/routes/brands/page.tsx" highlights={queryHighlights} +const [currentPage, setCurrentPage] = useState(0) +const limit = 15 +const offset = useMemo(() => { + return currentPage * limit +}, [currentPage]) + +const { data } = useQuery({ + queryFn: () => sdk.client.fetch(`/admin/brands`, { + query: { + limit, + offset, + }, + }), + queryKey: [["brands", limit, offset]], }) ``` -You export a `config` variable defined using the `defineRouteConfig` utility. +You first define pagination-related variables: + +- `currentPage`: A zero-based index of the current page of items. +- `limit`: The maximum number of items per page. +- `offset`: The number of items to skip before retrieving the page's items. This is calculated from the `currentPage` and `limit` variables. + +Then, you use `useQuery` from [Tanstack (React) Query](https://tanstack.com/query/latest) to query the Medusa server. Tanstack Query provides features like asynchronous state management and optimized caching. + +In the `queryFn` function that executes the query, you use the JS SDK's `client.fetch` method to send a request to your custom API route. The first parameter is the route's path, and the second is an object of request configuration and data. You pass the query parameters in the `query` property. + +This sends a request to the [Get Brands API route](#1-get-brands-api-route), passing the pagination query parameters. Whenever `currentPage` is updated, the `offset` is also updated, which will send a new request to retrieve the brands for the current page. + +### Display Brands Table + +Finally, you'll display the brands in a table using the component you created earlier. Import the component at the top of `src/admin/routes/brands/page.tsx`: + +```tsx title="src/admin/routes/brands/page.tsx" +import { Table } from "../../components/table" +``` + +Then, replace the `{/* TODO show brands */}` in the return statement with the following: -This indicates that a new item should be added to the sidebar with the title `Brands` and an icon from the [Medusa Icons package](!ui!/icons/overview). +```tsx title="src/admin/routes/brands/page.tsx" + +``` + +This renders a table that shows the ID and name of the brands. --- ## Test it Out -To test it out, start the Medusa application and login into the Medusa Admin. +To test out the UI route, start the Medusa application: -You'll find a new "Brands" sidebar item. If you click on it, a new page opens showing the list of brands in your store. +```bash npm2yarn +npm run dev +``` + +Then, open the admin dashboard at `http://localhost:9000/app`. After you log in, you'll find a new "Brands" sidebar item. Click on it to see the brands in your store. You can also go to `http://localhost:9000/app/brands` to see the page. + +![A new sidebar item is added for the new brands UI route. The UI route shows the table of brands with pagination.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733421074/Medusa%20Book/Screenshot_2024-12-05_at_7.46.52_PM_slcdqd.png) --- ## Summary -By following the examples of the previous chapters, you: +By following the previous chapters, you: -- Created a widget that showed the brand of a product in the Medusa Admin. -- Created a UI route that showed the list of brands in the Medusa Admin. +- Injected a widget into the product details page to show the product's brand. +- Created a UI route in the Medusa Admin that shows the list of brands. --- -## Next Steps +## Next Steps: Integrate Third-Party Systems + +Your customizations often span across systems, where you need to retrieve data or perform operations in a third-party system. -In the next chapters, you'll learn how to integrate third-party systems into your Medusa application to sync brands. +In the next chapters, you'll learn about the concepts that facilitate integrating third-party systems in your application. You'll integrate a dummy third-party system and sync the brands between it and the Medusa application. diff --git a/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx b/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx index 537627544804d..a78b64474ec37 100644 --- a/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx +++ b/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx @@ -1,64 +1,132 @@ import { Prerequisites } from "docs-ui" export const metadata = { - title: `${pageNumber} Show Brand of Product in Admin`, + title: `${pageNumber} Guide: Add Product's Brand Widget in Admin`, } # {metadata.title} - +In this chapter, you'll customize the product details page of the Medusa Admin dashboard to show the product's [brand](../../custom-features/module/page.mdx). You'll create a widget that is injected into a pre-defined zone in the page, and in the widget you'll retrieve the product's brand from the server and display it. -This chapter covers how to show the brand of a product in the Medusa Admin using a widget as a step of the ["Customize Admin" chapter](../page.mdx). + + +## 1. Initialize JS SDK + +In your custom widget, you'll retrieve the product's brand by sending a request to the Medusa server. Medusa has a [JS SDK](!resources!/js-sdk) that simplifies sending requests to the server's API routes. + +So, you'll start by configuring the JS SDK. Create the file `src/admin/lib/sdk.ts` with the following content: + +![The directory structure of the Medusa application after adding the file](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414606/Medusa%20Book/brands-admin-dir-overview-1_jleg0t.jpg) + +```ts title="src/admin/lib/sdk.ts" +import Medusa from "@medusajs/js-sdk" + +export const sdk = new Medusa({ + baseUrl: "http://localhost:9000", + debug: process.env.NODE_ENV === "development", + auth: { + type: "session", + }, +}) +``` + +You initialize the SDK passing it the following options: + +- `baseUrl`: The URL to the Medusa server. +- `debug`: Whether to enable logging debug messages. This should only be enabled in development. +- `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard. + +You can now use the SDK to send requests to the Medusa server. + + + +Learn more about the JS SDK and its options in [this reference](!resources!/js-sdk). -## Widget to Show Brand in Product Details +--- + +## 2. Add Widget to Product Details Page + +You'll now add a widget to the product-details page. A widget is a React component that's injected into pre-defined zones in the Medusa Admin dashboard. It's created in a `.tsx` file under the `src/admin/widgets` directory. + + + +Learn more about widgets in [this documentation](../../../advanced-development/admin/widgets/page.mdx). + + To create a widget that shows a product's brand in its details page, create the file `src/admin/widgets/product-brand.tsx` with the following content: +![Directory structure of the Medusa application after adding the widget](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414684/Medusa%20Book/brands-admin-dir-overview-2_eq5xhi.jpg) + export const highlights = [ - ["7", "data", "Receive the product's details as a prop"], - ["9", "brand", "A state variable to store the brand"], - ["19", "fetch", "Retrieve the brand of a product using the custom API route"], - ["41", "zone", "Show the widget at the top of the product details page."] + ["14", "ProductBrandWidget", "Widget to inject into the page"], + ["15", "data", "Receive the product's details as a prop"], + ["17", "useQuery", "Use Tanstack Query to send the request to the server with the JS SDK."], + ["18", "sdk", "Send the request to retrieve the product with the JS SDK."], + ["19", "fields", "Specify the product's brand to be retrieved."], + ["23", "brandName", "Get brand name from the query request."], + ["53", "defineWidgetConfig", "Export the widget's configurations"], + ["54", "zone", "Show the widget at the top of the product details page."] ] ```tsx title="src/admin/widgets/product-brand.tsx" highlights={highlights} import { defineWidgetConfig } from "@medusajs/admin-sdk" import { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types" -import { useEffect, useState } from "react" -import { Container, Heading } from "@medusajs/ui" +import { clx, Container, Heading, Text } from "@medusajs/ui" +import { useQuery } from "@tanstack/react-query" +import { sdk } from "../lib/sdk" + +type AdminProductBrand = AdminProduct & { + brand?: { + id: string + name: string + } +} const ProductBrandWidget = ({ - data, + data: product, }: DetailWidgetProps) => { - const [brand, setBrand] = useState< - Record | undefined - >() - const [loading, setLoading] = useState(true) - - useEffect(() => { - if (!loading) { - return - } + const { data: queryResult } = useQuery({ + queryFn: () => sdk.admin.product.retrieve(product.id, { + fields: "+brand.*", + }), + queryKey: [["product", product.id]], + }) + const brandName = (queryResult?.product as AdminProductBrand)?.brand?.name - fetch(`/admin/products/${data.id}?fields=+brand.*`, { - credentials: "include", - }) - .then((res) => res.json()) - .then(({ product }) => { - setBrand(product.brand) - setLoading(false) - }) - }, [loading]) - return (
- Brand +
+ Brand +
+
+
+ + Name + + + + {brandName || "-"} +
- {loading && Loading...} - {brand && Name: {brand.name}} ) } @@ -70,32 +138,41 @@ export const config = defineWidgetConfig({ export default ProductBrandWidget ``` -This adds a widget at the top of the product's details page. +A widget's file must export: - +- A React component to be rendered in the specified injection zone. The component must be the file's default export. +- A configuration object created with `defineWidgetConfig` from the Admin Extension SDK. The function receives an object as a parameter that has a `zone` property, whose value is the zone to inject the widget to. -Learn more about widgets [in this guide](../../../basics/admin-customizations/page.mdx). +Since the widget is injected at the top of the product details page, the widget receives the product's details as a parameter. - +In the widget, you use [Tanstack (React) Query](https://tanstack.com/query/latest) to query the Medusa server. Tanstack Query provides features like asynchronous state management and optimized caching. In the `queryFn` function that executes the query, you use the JS SDK to send a request to the [Get Product API Route](!api!/admin#products_getproductsid), passing `+brand.*` in the `fields` query parameter to retrieve the product's brand. -Widgets created in a details page receive the targetted item in a `data` prop. So, the `ProductBrandWidget` receives the product's details in the `data` prop. +You then render a section that shows the brand's name. In admin customizations, use components from the [Medusa UI package](!ui!) to maintain a consistent user interface and design in the dashboard. -In the widget, you fetch the product's brand using the [Get Product API route](!api!/admin#products_getproductsid), passing it the query parameter `fields=+brand.*` to retrieve the product's brand. +--- - +## Test it Out -Admin customizations can use the [Medusa UI package](!ui!) to align your customizations with the admin's design. Also, [this guide](!resources!/admin-components) includes examples of common components in the Medusa Admin. +To test out your widget, start the Medusa application: - +```bash npm2yarn +npm run dev +``` + +Then, open the admin dashboard at `http://localhost:9000/app`. After you log in, open the page of a product that has a brand. You'll see a new section at the top showing the brand's name. + +![The widget is added as the first section of the product details page.](https://res.cloudinary.com/dza7lstvk/image/upload/v1733414415/Medusa%20Book/Screenshot_2024-12-05_at_5.59.25_PM_y85m14.png) --- -## Test it Out +## Admin Components Guides + +When building your widget, you may need more complicated components. For example, you may add a form to the above widget to set the product's brand. -Start your Medusa application and go to a product's details page in the Medusa Admin, you'll find a new block at the top of the page showing the product's brand. +The [Admin Components guides](!resources!/admin-components) show you how to build and use common components in the Medusa Admin, such as forms, tables, JSON data viewer, and more. The components in the guides also follow the Medusa Admin's design convention. --- -## Next Chapter: Add List of Brands Page +## Next Chapter: Add UI Route for Brands -In the next chapter, you'll add a new page or UI route that displays the list of brands in your application. +In the next chapter, you'll add a UI route that displays the list of brands in your application and allows admin users. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 43c3150d58874..ec5da6af6327e 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -94,9 +94,9 @@ export const generatedEditDates = { "app/learn/customization/custom-features/workflow/page.mdx": "2024-11-28T10:47:28.084Z", "app/learn/customization/extend-features/extend-create-product/page.mdx": "2024-12-05T09:26:15.796Z", "app/learn/customization/custom-features/page.mdx": "2024-11-28T08:21:55.207Z", - "app/learn/customization/customize-admin/page.mdx": "2024-09-12T12:25:29.853Z", - "app/learn/customization/customize-admin/route/page.mdx": "2024-10-07T12:43:11.335Z", - "app/learn/customization/customize-admin/widget/page.mdx": "2024-12-05T10:40:56.611Z", + "app/learn/customization/customize-admin/page.mdx": "2024-12-06T07:21:02.303Z", + "app/learn/customization/customize-admin/route/page.mdx": "2024-12-06T08:29:57.834Z", + "app/learn/customization/customize-admin/widget/page.mdx": "2024-12-06T08:15:11.426Z", "app/learn/customization/extend-features/define-link/page.mdx": "2024-12-04T17:15:16.004Z", "app/learn/customization/extend-features/page.mdx": "2024-09-12T12:38:57.394Z", "app/learn/customization/extend-features/query-linked-records/page.mdx": "2024-12-05T10:36:32.357Z", diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index f61486a6b5961..382db13feb7cd 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -142,7 +142,7 @@ export const sidebar = numberSidebarItems( children: [ { type: "link", - title: "Add Widgets", + title: "Add Widget", path: "/learn/customization/customize-admin/widget", }, {