From 2bb5798d5da92c947e50347afca141ad6b1709ef Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 17 Aug 2018 14:41:48 -0500 Subject: [PATCH 1/4] Add breadcrumb info --- guides/v2.3/graphql/index.md | 4 ++ guides/v2.3/graphql/reference/categories.md | 66 +++++++++++++-------- 2 files changed, 46 insertions(+), 24 deletions(-) diff --git a/guides/v2.3/graphql/index.md b/guides/v2.3/graphql/index.md index 73f99ef017f..1a6b4502394 100644 --- a/guides/v2.3/graphql/index.md +++ b/guides/v2.3/graphql/index.md @@ -53,3 +53,7 @@ GraphiQL is an in-browser tool for writing, validating, and testing GraphQL quer ![GraphiQL browser]({{ page.baseurl }}/graphql/images/graphql-browser.png) To begin using GraphiQL, set the GraphQL endpoint by entering `http:///graphql` in the URL bar, then click **Set endpoint**. You can use the browser in the right column to determine how to set up a query. Additional examples are also available at [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html). + + +{:.bs-callout .bs-callout-info} +You can access the GraphQL introspection feature only if your Magento instance is in developer mode. See [Set the Magento mode]({{ page.baseurl }}/config-guide/cli/config-cli-subcommands-mode.html) for more information about modes. diff --git a/guides/v2.3/graphql/reference/categories.md b/guides/v2.3/graphql/reference/categories.md index f4422bfd6a0..cf13101da5e 100644 --- a/guides/v2.3/graphql/reference/categories.md +++ b/guides/v2.3/graphql/reference/categories.md @@ -4,11 +4,11 @@ title: category endpoint version: 2.3 --- -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. ## Query structure -``` json +``` category ( id: int ): CategoryTree @@ -40,7 +40,11 @@ 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()` | `CategoryProducts` | The list of products assigned to the category -`children` | `CategoryTree` | +`breadcrumbs` | `Breadcrumb` | +`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: @@ -48,9 +52,7 @@ 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. See [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) for more information. The `CategoryProducts` object contains the following attributes: @@ -61,28 +63,24 @@ 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. + +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 -## Sample 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 %} +``` { category(id: 20) { products { @@ -119,4 +117,24 @@ The following query returns information about category ID `20` and four levels o } } } -{% endhighlight %} +``` + +The following query returns breadcrumb information about the women's tops category (`id` = 25). + +``` +{ + category ( + id: 25 +) { + id + level + name + breadcrumbs { + category_id + category_name + category_level + category_url_key + } + } +} +``` From e179f2d6d2de7693ee82f7d3960869478a888cbb Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 17 Aug 2018 17:45:41 -0500 Subject: [PATCH 2/4] editorial comments --- guides/v2.3/graphql/index.md | 2 +- guides/v2.3/graphql/reference/categories.md | 118 +++++++++++++++++++- 2 files changed, 116 insertions(+), 4 deletions(-) diff --git a/guides/v2.3/graphql/index.md b/guides/v2.3/graphql/index.md index 95f1754d458..4b3f19af7c7 100644 --- a/guides/v2.3/graphql/index.md +++ b/guides/v2.3/graphql/index.md @@ -55,4 +55,4 @@ To begin using GraphiQL, set the GraphQL endpoint by entering `http://)` | `CategoryProducts` | The list of products assigned to the category -`breadcrumbs` | `Breadcrumb` | +`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information about each category that `children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories. @@ -51,7 +51,7 @@ 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. +`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. The `CategoryProducts` object contains the following attributes: @@ -74,11 +74,16 @@ Attribute | Data type | Description `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. +**Request** + ``` { category(id: 20) { @@ -117,9 +122,88 @@ The following query returns information about category ID `20` and four levels o } } ``` +**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 ( @@ -137,3 +221,31 @@ The following query returns breadcrumb information about the women's tops catego } } ``` + +**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" + } + ] + } + } +} +``` From 2ae5f53a8338b550ccecc61a72f5c9a4d3840e74 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 17 Aug 2018 21:10:01 -0500 Subject: [PATCH 3/4] editorial comments --- guides/v2.3/graphql/reference/categories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/v2.3/graphql/reference/categories.md b/guides/v2.3/graphql/reference/categories.md index 94154d9294d..8a9ab6e2e4d 100644 --- a/guides/v2.3/graphql/reference/categories.md +++ b/guides/v2.3/graphql/reference/categories.md @@ -39,7 +39,7 @@ 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()` | `CategoryProducts` | The list of products assigned to the category -`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information about each category that +`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. From d8275692eac2d75d761a215c5b41b204fc0b3019 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 20 Aug 2018 14:18:34 -0500 Subject: [PATCH 4/4] Update categories.md --- guides/v2.3/graphql/reference/categories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/v2.3/graphql/reference/categories.md b/guides/v2.3/graphql/reference/categories.md index 8a9ab6e2e4d..67d3e8babef 100644 --- a/guides/v2.3/graphql/reference/categories.md +++ b/guides/v2.3/graphql/reference/categories.md @@ -3,7 +3,7 @@ group: graphql title: category endpoint --- -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. +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 unless the `queryDepth` parameter in the GraphQL `di.xml` file has been reconfigured. ## Query structure