[]
+ 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 component accepts the following props:
+
+- `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.
+
+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
+
+You'll now update the UI route to retrieve the brands from the API route you added earlier.
+
+First, add the following type in `src/admin/routes/brands/page.tsx`:
+
+```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 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:
+
+```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.
+
+
---
## 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
-In the next chapters, you'll learn how to integrate third-party systems into your Medusa application to sync brands.
+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 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 5376275448..a78b64474e 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:
+
+
+
+```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:
+
+
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)
+ 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
- useEffect(() => {
- if (!loading) {
- return
- }
-
- fetch(`/admin/products/${data.id}?fields=+brand.*`, {
- credentials: "include",
- })
- .then((res) => res.json())
- .then(({ product }) => {
- setBrand(product.brand)
- setLoading(false)
- })
- }, [loading])
-
return (
+
+
+ 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.
-
-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.
-
-
-
-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 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.
---
## Test it Out
-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.
+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.
+
+
---
-## Next Chapter: Add List of Brands Page
+## Admin Components Guides
-In the next chapter, you'll add a new page or UI route that displays the list of brands in your application.
+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.
+
+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 UI Route for Brands
+
+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 43c3150d58..ec5da6af63 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 f61486a6b5..382db13feb 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",
},
{