docs: add routing page (#9550)

- Add a new homepage to `book` project for the routing page - Move all main doc pages to be under `/v2/learn` (and added redirects + fixed links across docs) - Other: add admin components to resources dropdown + fixes to search on mobile. Closes DX-955 Preview: https://docs-v2-git-docs-router-page-medusajs.vercel.app/v2
2024-10-18 08:24:34 +00:00
parent 7a47f5211d
commit 0a37675f0e
223 changed files with 2549 additions and 696 deletions
@@ -0,0 +1,130 @@
+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."], 
+  ["17", "zone", "The zone to inject the widget to."]
+]
+
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+
+// The widget
+const ProductWidget = () => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Product Widget</Heading>
+      </div>
+    </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-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.
+
+In the example above, the widget is injected at the top of a product’s details.
+
+<Note title="Important" type="warning">
+
+The widget component must be created as an arrow function.
+
+</Note>
+
+---
+
+## 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."],
+  ["16", "data.title", "Show the product's title."]
+]
+
+```tsx title="src/admin/widgets/product-widget.tsx" highlights={detailHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+import { 
+  DetailWidgetProps, 
+  AdminProduct,
+} from "@medusajs/framework/types"
+
+// The widget
+const ProductWidget = ({ 
+  data,
+}: DetailWidgetProps<AdminProduct>) => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">
+          Product Widget {data.title}
+        </Heading>
+      </div>
+    </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.