From 5996089c9c4cfe7ed6b5c3e52e2a9e3b1b41395c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 27 Aug 2024 11:35:09 +0300 Subject: [PATCH] docs: added new guides and troubleshooting related to admin development (#8739) --- .../admin/constraints/page.mdx | 58 +++++++++++++++++++ www/apps/book/sidebar.mjs | 7 ++- .../medusa-admin/no-widget-route/page.mdx | 37 ++++++++++++ www/apps/resources/generated/edit-dates.mjs | 3 +- www/apps/resources/generated/files-map.mjs | 4 ++ www/apps/resources/generated/sidebar.mjs | 16 +++++ www/apps/resources/sidebar.mjs | 11 ++++ 7 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 www/apps/book/app/advanced-development/admin/constraints/page.mdx create mode 100644 www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx diff --git a/www/apps/book/app/advanced-development/admin/constraints/page.mdx b/www/apps/book/app/advanced-development/admin/constraints/page.mdx new file mode 100644 index 0000000000..37ee2c7e9c --- /dev/null +++ b/www/apps/book/app/advanced-development/admin/constraints/page.mdx @@ -0,0 +1,58 @@ +export const metadata = { + title: `${pageNumber} Admin Development Constraints`, +} + +# {metadata.title} + +This chapter lists some constraints of admin widgets and UI routes. + +## Arrow Functions + +Widget and UI route components must be created as arrow functions. + +export const arrowHighlights = [ + ["2", "function", "Don't declare the widget / UI route as a function."], + ["7", "() => ", "Use arrow functions when creating a widget / UI route."] +] + +```ts highlights={arrowHighlights} +// Don't +function ProductWidget () { + // ... +} + +// Do +const ProductWidget = () => { + // ... +} +``` + +--- + +## Widget Zone + +A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable. + +export const zoneHighlights = [ + ["3", "`product.details.before`", "Don't specify the value of `zone` as a template literal."], + ["9", "ZONE", "Don't specify a variable as the value of `zone`."], + ["14", `"product.details.before"`, "Wrap the value of `zone` in double or single quotes."] +] + +```ts highlights={zoneHighlights} +// Don't +export const config = defineWidgetConfig({ + zone: `product.details.before`, +}) + +// Don't +const ZONE = "product.details.after" +export const config = defineWidgetConfig({ + zone: ZONE, +}) + +// Do +export const config = defineWidgetConfig({ + zone: "product.details.before", +}) +``` diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index 672f74f4fb..9fb5d2960c 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -251,7 +251,7 @@ export const sidebar = numberSidebarItems( { type: "link", path: "/advanced-development/workflows/constructor-constraints", - title: "Workflow Constraints", + title: "Constraints", }, { type: "link", @@ -330,6 +330,11 @@ export const sidebar = numberSidebarItems( path: "/advanced-development/admin/ui-routes", title: "Admin UI Routes", }, + { + type: "link", + path: "/advanced-development/admin/constraints", + title: "Constraints", + }, { type: "link", path: "/advanced-development/admin/tips", diff --git a/www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx b/www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx new file mode 100644 index 0000000000..c418ddede6 --- /dev/null +++ b/www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx @@ -0,0 +1,37 @@ +export const metadata = { + title: `Admin Widget / UI Route Not Showing`, +} + +# {metadata.title} + +This guide provides some troubleshooting step as to why your admin widget / UI route isn't showing in the Medusa Admin dashboard. + +## Incorrect Zone + +If you're adding an admin widget, make sure you're using a correct zone. + +Refer to the [Admin Widget Injection Zones list](../../../admin-widget-injection-zones/page.mdx) for reference. + +--- + +## Incorrect Function Definition + +Widget and UI routes must be defined as arrow functions. Any other type of declaration isn't accepted. + +Refer to the [Admin Development Constraints](!docs!/advanced-development/admin/constraints) documentation for more details. + +--- + +## Incorrect Type of Zone Value + +A widget zone's value must be wrapped in double or single quotes: + +```ts +export const config = defineWidgetConfig({ + zone: "product.details.before", +}) +``` + +Any other usage leads to the widget not being shown. + +Refer to the [Admin Development Constraints](!docs!/advanced-development/admin/constraints) documentation for more details. diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 393c0c4447..99884dcd22 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -267,5 +267,6 @@ export const generatedEditDates = { "references/core_flows/Order/functions/core_flows.Order.updateOrderEditAddItemWorkflow/page.mdx": "2024-08-20T00:10:59.105Z", "references/core_flows/core_flows.Order/page.mdx": "2024-08-20T00:10:56.437Z", "references/modules/core_flows/page.mdx": "2024-08-20T00:10:49.141Z", - "references/types/types.HttpTypes/page.mdx": "2024-08-20T00:10:43.061Z" + "references/types/types.HttpTypes/page.mdx": "2024-08-20T00:10:43.061Z", + "app/troubleshooting/medusa-admin/no-widget-route/page.mdx": "2024-08-23T11:31:26.346Z" } \ No newline at end of file diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index 2704fe66d3..380b86b86f 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/www/apps/resources/generated/files-map.mjs @@ -1007,6 +1007,10 @@ export const filesMap = [ "filePath": "/www/apps/resources/app/troubleshooting/general-errors/page.mdx", "pathname": "/troubleshooting/general-errors" }, + { + "filePath": "/www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx", + "pathname": "/troubleshooting/medusa-admin/no-widget-route" + }, { "filePath": "/www/apps/resources/app/troubleshooting/page.mdx", "pathname": "/troubleshooting" diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs index 7d036252fc..81f104a30b 100644 --- a/www/apps/resources/generated/sidebar.mjs +++ b/www/apps/resources/generated/sidebar.mjs @@ -8371,6 +8371,22 @@ export const generatedSidebar = [ } ] }, + { + "loaded": true, + "isPathHref": true, + "type": "category", + "title": "Admin Development", + "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "path": "/troubleshooting/medusa-admin/no-widget-route", + "title": "Widget or Route not Showing", + "children": [] + } + ] + }, { "loaded": true, "isPathHref": true, diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs index 2ff9c0bc03..4aa419de29 100644 --- a/www/apps/resources/sidebar.mjs +++ b/www/apps/resources/sidebar.mjs @@ -2160,6 +2160,17 @@ export const sidebar = sidebarAttachHrefCommonOptions([ }, ], }, + { + type: "category", + title: "Admin Development", + children: [ + { + type: "link", + path: "/troubleshooting/medusa-admin/no-widget-route", + title: "Widget or Route not Showing", + }, + ], + }, { type: "category", title: "Upgrade",