From 263dbf7872886b51ce8a8e03875dea25d14b188b Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 27 Nov 2024 18:52:33 +0200 Subject: [PATCH] docs: update details on retrieving nested categories (#10317) --- .../categories/nested-categories/page.mdx | 26 +++++++++++++------ www/apps/resources/generated/edit-dates.mjs | 2 +- .../admin/get_admin_product-categories.ts | 8 +++--- .../get_admin_product-categories_[id].ts | 8 +++--- .../store/get_store_product-categories.ts | 8 +++--- .../get_store_product-categories_[id].ts | 8 +++--- 6 files changed, 35 insertions(+), 25 deletions(-) diff --git a/www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx b/www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx index 14df668f7e3d2..67a1e567f1605 100644 --- a/www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx +++ b/www/apps/resources/app/storefront-development/products/categories/nested-categories/page.mdx @@ -8,7 +8,11 @@ export const metadata = { A product category has parent and child categories. -To retrieve the child or nested categories of a category in your storefront, pass `*category_children` to the `fields` query parameter of the [Get a Category API Route](!api!/store#product-categories_getproductcategoriesid). +To retrieve the child or nested categories of a category in your storefront, pass to the [Get a Category API Route](!api!/store#product-categories_getproductcategoriesid) the following query parameters: + +- `include_descendants_tree=true` to retrieve each category's nested categories at all levels. +- Add `category_children` to `fields`, which is the field that will hold a category's nested categories. You can either pass `*category_children` to retrieve all fields of a child category, or specify the fields specifically to avoid a large response size. For example, `field=category_children.id,category_children.name`. +- `parent_category_id=null` to retrieve only the categories that don't have a parent. This avoids retrieving the child categories multiple times in the response since child categories are now set in their parent's object. For example: @@ -16,12 +20,16 @@ For example: export const fetchHighlights = [ - ["2", `"*category_children"`, "Select the `category_children` relation."], + ["2", `"category_children.id,category_children.name"`, "Select the fields of category children"], + ["3", `"include_descendants_tree"`, "Indicate that all nested categories should be retrieved."], + ["4", "parent_category_id", "Since each category will have its children, you only retrieve categories that don't have a parent."] ] ```ts highlights={fetchHighlights} const searchParams = new URLSearchParams({ - fields: "*category_children", + fields: "category_children.id,category_children.name", + include_descendants_tree: true, + parent_category_id: null }) fetch(`http://localhost:9000/store/product-categories/${id}?${ @@ -44,10 +52,11 @@ export const fetchHighlights = [ export const highlights = [ ["12", "{ params: { id } }: Params", "This is based on Next.js which passes the path parameters as a prop."], - ["24", `"*category_children"`, "Select the `category_children` relation."], - ["27"], ["28"], ["29"], - ["30"], ["31"], ["32"], ["33"], ["34"], ["35"], ["36"], ["37"], ["38"], ["39"], - ["53", "", "Show the nested categories."], + ["24", `"category_children.id,category_children.name"`, "Select the fields of category children"], + ["25", "parent_category_id", "Since each category will have its children, you only retrieve categories that don't have a parent."] + ["26"], ["27"], ["28"], + ["29"], ["30"], ["31"], ["32"], ["33"], ["34"], ["35"], ["36"], ["37"], ["38"], + ["54", "", "Show the nested categories."], ] ```tsx highlights={highlights} @@ -74,7 +83,8 @@ export const highlights = [ } const searchParams = new URLSearchParams({ - fields: "*category_children", + fields: "category_children.id,category_children.name", + parent_category_id: null }) fetch(`http://localhost:9000/store/product-categories/${id}?${ diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 43b651839065a..e60a20306e55b 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -172,7 +172,7 @@ export const generatedEditDates = { "app/storefront-development/customers/retrieve/page.mdx": "2024-09-11T09:55:40.516Z", "app/storefront-development/customers/page.mdx": "2024-06-13T12:21:54+03:00", "app/storefront-development/products/categories/list/page.mdx": "2024-09-11T10:01:50.873Z", - "app/storefront-development/products/categories/nested-categories/page.mdx": "2024-09-11T10:02:28.405Z", + "app/storefront-development/products/categories/nested-categories/page.mdx": "2024-11-27T12:00:57.628Z", "app/storefront-development/products/categories/products/page.mdx": "2024-09-11T10:08:05.194Z", "app/storefront-development/products/categories/retrieve/page.mdx": "2024-09-11T10:04:38.752Z", "app/storefront-development/products/categories/page.mdx": "2024-06-11T19:55:56+02:00", diff --git a/www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts b/www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts index ee8c3688f7e35..4db18e6bf1e3e 100644 --- a/www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts +++ b/www/utils/generated/oas-output/operations/admin/get_admin_product-categories.ts @@ -111,20 +111,20 @@ * description: A parent category's ID. * - name: include_ancestors_tree * in: query - * description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object. + * description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * required: false * schema: * type: boolean * title: include_ancestors_tree - * description: Whether to include the parent category of each category. If enabled, the parent category is set in the `parent_category` property of each category object. + * description: Whether to include the parent category of each category. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * - name: include_descendants_tree * in: query - * description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object. + * description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * required: false * schema: * type: boolean * title: include_descendants_tree - * description: Whether to include the child categories of each category. If enabled, the child categories are added to the `category_children` property of each category object. + * description: Whether to include the child categories of each category. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * - name: is_internal * in: query * description: Filter by whether the category is internal. diff --git a/www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts b/www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts index 47fd023f6ade7..3662dd2c3e5d0 100644 --- a/www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts +++ b/www/utils/generated/oas-output/operations/admin/get_admin_product-categories_[id].ts @@ -25,20 +25,20 @@ * url: "#select-fields-and-relations" * - name: include_ancestors_tree * in: query - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * required: false * schema: * type: boolean * title: include_ancestors_tree - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * - name: include_descendants_tree * in: query - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * required: false * schema: * type: boolean * title: include_descendants_tree - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * security: * - api_token: [] * - cookie_auth: [] diff --git a/www/utils/generated/oas-output/operations/store/get_store_product-categories.ts b/www/utils/generated/oas-output/operations/store/get_store_product-categories.ts index cc7bdfd2f3623..5314b03478789 100644 --- a/www/utils/generated/oas-output/operations/store/get_store_product-categories.ts +++ b/www/utils/generated/oas-output/operations/store/get_store_product-categories.ts @@ -114,20 +114,20 @@ * description: A product category's ID. * - name: include_ancestors_tree * in: query - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * required: false * schema: * type: boolean * title: include_ancestors_tree - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * - name: include_descendants_tree * in: query - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * required: false * schema: * type: boolean * title: include_descendants_tree - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the child of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * - name: created_at * in: query * description: Filter by the category's creation date. diff --git a/www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts b/www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts index 53748a15b0589..f6c58e03c0b4a 100644 --- a/www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts +++ b/www/utils/generated/oas-output/operations/store/get_store_product-categories_[id].ts @@ -28,20 +28,20 @@ * url: "#select-fields-and-relations" * - name: include_ancestors_tree * in: query - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * required: false * schema: * type: boolean * title: include_ancestors_tree - * description: Whether to retrieve the category's parent. When enabled, the parent category is set in the `parent_category` property. + * description: Whether to retrieve the category's parent. If you enable this, add to the `fields` query parameter `parent_category` to set the parent of a category in this field. You can either pass `*parent_category` to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, `fields=parent_category.id,parent_category.name`. * - name: include_descendants_tree * in: query - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * required: false * schema: * type: boolean * title: include_descendants_tree - * description: Whether to retrieve a list of child categories. When enabled, the parent categories are added to the `category_children` property. + * description: Whether to retrieve a list of child categories. If you enable this, add to the `fields` query parameter `category_children` to set the children of a category in this field. You can either pass `*category_children` to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, `fields=category_children.id,category_children.name`. * x-codeSamples: * - lang: Shell * label: cURL