-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add breadcrumb info to GraphQL categories topic #2767
Changes from 4 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,11 +3,11 @@ group: graphql | |
title: category endpoint | ||
--- | ||
|
||
The `category` endpoint allows you to search for a single category definition or the entire category tree. | ||
The `category` endpoint allows you to search for a single category definition or the entire category tree. To return multiple category levels in a single call, define the response so that it contains up to ten nested `children` options. You cannot return the entire category tree if it contains more than 10 sublevels. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure if it helps, but consider adding a "for example" define a response so that it contains up to ten nested Also, in the Sample Queries section -- It might be good to show a real response for the CategoryTree query since it's kind of complicated. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I left the description as is, but added sample output. |
||
## Query structure | ||
|
||
``` json | ||
``` | ||
category ( | ||
id: int | ||
): CategoryTree | ||
|
@@ -39,17 +39,19 @@ Attribute | Data type | Description | |
`product_count`| Int | The number of products in the category | ||
`default_sort_by`| String | The attribute to use for sorting | ||
`products(<attributes>)` | `CategoryProducts` | The list of products assigned to the category | ||
`children` | `CategoryTree` | | ||
`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information the categories that comprise the breadcrumb trail for the specified category | ||
`children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories. | ||
|
||
|
||
#### CategoryProducts object | ||
|
||
The `products` attribute can contain the following attributes: | ||
|
||
Attribute | Data type | Description | ||
--- | --- | --- | ||
`pageSize` | Int | Specifies the maximum number of results to return at once. This attribute is optional. The default value is 20. | ||
`currentPage` | Int | Specifies which page of results to return. The default value is 1. | ||
`sort` | `ProductSortInput` Specifies which attribute to sort on, and whether to return the results in ascending or descending order. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information. | ||
|
||
#### CategoryProducts | ||
`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) describes sort orders. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I like the way you changed the "See" reference 🥇 |
||
The `CategoryProducts` object contains the following attributes: | ||
|
||
|
@@ -60,28 +62,29 @@ Attribute | Data type | Description | |
`total_count` | Int | The number of products returned | ||
|
||
|
||
The response can contain up to ten nested `children` options that allow you to return multiple levels of the category tree. In most cases, the entire category tree can be returned in a single call. The following response definition returns two levels of categories: | ||
#### Breadcrumb object | ||
|
||
{% highlight json %} | ||
{ | ||
category_tree { | ||
id | ||
level | ||
name | ||
children { | ||
id | ||
level | ||
name | ||
} | ||
} | ||
} | ||
{% endhighlight %} | ||
A breadcrumb trail is a set of links that shows customers where they are in relation to other pages in the | ||
store. | ||
|
||
## Sample Query | ||
Attribute | Data type | Description | ||
--- | --- | --- | ||
`category_id` | Int | An ID that uniquely identifies the category | ||
`category_name` | String | The display name of the category | ||
`category_level` | Int | Indicates the depth of the category within the tree | ||
`category_url_key` | String | The url key assigned to the category | ||
|
||
#### CategoryTree object | ||
|
||
This `CategoryTree` object contains information about the next level of subcategories of the category specified in the original query. | ||
|
||
## Sample Queries | ||
|
||
The following query returns information about category ID `20` and four levels of subcategories. In the sample data, category ID `20` is assigned to the "Women" category. | ||
|
||
{% highlight json %} | ||
**Request** | ||
|
||
``` | ||
{ | ||
category(id: 20) { | ||
products { | ||
|
@@ -118,4 +121,131 @@ The following query returns information about category ID `20` and four levels o | |
} | ||
} | ||
} | ||
{% endhighlight %} | ||
``` | ||
**Response** | ||
|
||
``` json | ||
{ | ||
"data": { | ||
"category": { | ||
"products": { | ||
"total_count": 0, | ||
"page_info": { | ||
"current_page": 1, | ||
"page_size": 20 | ||
} | ||
}, | ||
"children_count": "8", | ||
"children": [ | ||
{ | ||
"id": 21, | ||
"level": 3, | ||
"name": "Tops", | ||
"path": "1/2/20/21", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 22, | ||
"level": 3, | ||
"name": "Bottoms", | ||
"path": "1/2/20/22", | ||
"children": [ | ||
{ | ||
"id": 23, | ||
"level": 4, | ||
"name": "Jackets", | ||
"path": "1/2/20/21/23", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 24, | ||
"level": 4, | ||
"name": "Hoodies & Sweatshirts", | ||
"path": "1/2/20/21/24", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 25, | ||
"level": 4, | ||
"name": "Tees", | ||
"path": "1/2/20/21/25", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 26, | ||
"level": 4, | ||
"name": "Bras & Tanks", | ||
"path": "1/2/20/21/26", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 27, | ||
"level": 4, | ||
"name": "Pants", | ||
"path": "1/2/20/22/27", | ||
"children": [] | ||
}, | ||
{ | ||
"id": 28, | ||
"level": 4, | ||
"name": "Shorts", | ||
"path": "1/2/20/22/28", | ||
"children": [] | ||
} | ||
] | ||
} | ||
] | ||
} | ||
} | ||
} | ||
``` | ||
|
||
The following query returns breadcrumb information about the women's tops category (`id` = 25). | ||
|
||
**Request** | ||
|
||
``` | ||
{ | ||
category ( | ||
id: 25 | ||
) { | ||
id | ||
level | ||
name | ||
breadcrumbs { | ||
category_id | ||
category_name | ||
category_level | ||
category_url_key | ||
} | ||
} | ||
} | ||
``` | ||
|
||
**Response** | ||
|
||
``` json | ||
{ | ||
"data": { | ||
"category": { | ||
"id": 25, | ||
"level": 4, | ||
"name": "Tees", | ||
"breadcrumbs": [ | ||
{ | ||
"category_id": 20, | ||
"category_name": "Women", | ||
"category_level": 2, | ||
"category_url_key": "women" | ||
}, | ||
{ | ||
"category_id": 21, | ||
"category_name": "Tops", | ||
"category_level": 3, | ||
"category_url_key": "tops-women" | ||
} | ||
] | ||
} | ||
} | ||
} | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a note, nesting level limit can be re-configured via di.xml by the system integrator.