Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

GraphQL: Add coverage for product reviews #7775

Merged
merged 9 commits into from
Aug 28, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/_data/toc/graphql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,10 @@ pages:
- label: isEmailAvailable query
url: /graphql/queries/is-email-available.html

- label: productReviewRatingsMetadata query
url: /graphql/queries/product-review-ratings-metadata.html
exclude_versions: ["2.3"]

- label: products query
url: /graphql/queries/products.html

Expand Down Expand Up @@ -192,6 +196,10 @@ pages:
- label: createPayPalExpressToken mutation
url: /graphql/mutations/create-paypal-express-token.html

- label: createProductReview mutation
url: /graphql/mutations/create-product-review.html
exclude_versions: ["2.3"]

- label: deleteCustomerAddress mutation
url: /graphql/mutations/delete-customer-address.html

Expand Down
1 change: 1 addition & 0 deletions src/_includes/graphql/customer-output-24.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Attribute | Data Type | Description
`middlename` |String | The customer's middle name
`orders(<FilterCriteria>)` | {{ customeroutput_text }} | A list of the customer's placed orders{{ crossref_text }}
`prefix` | String | An honorific, such as Dr., Mr., or Mrs.
`reviews(pageSize: Int = 20 currentPage: Int = 1)` | ProductReviews! | The list of reviews of the product
`reward_points` | RewardPoints | Details about the customer's reward points
`suffix` | String | A value such as Sr., Jr., or III
`taxvat` | String | The customer's Tax/VAT number (for corporate customers)
Expand Down
20 changes: 20 additions & 0 deletions src/_includes/graphql/product-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
The `ProductReview` object contains details about a product review. It contains the following attributes.

Attribute | Data Type | Description
--- | --- | ---
`average_rating` | Float! | The average rating for product review
`created_at` | String! | Date indicating when the review was created
`nickname` | String! | The customer's nickname. Defaults to the customer name, if logged in
`product` | ProductInterface! | Contains details about the reviewed product
`ratings_breakdown` | [ProductReviewRating!]! | An array of ratings by rating category, such as quality, price, and value
`summary` | String! | The summary (title) of the review
`text` | String! | The review text

### ProductReviewRating attributes {#ProductReviewRating}

The `ProductReviewRating` object contains the following attributes.

Attribute | Data Type | Description
--- | --- | ---
`name` | String! | The label assigned to an aspect of a product that is being rated, such as quality or price
`value` | String! | The rating value given by customer. By default, possible values range from 1 to 5
120 changes: 120 additions & 0 deletions src/guides/v2.4/graphql/mutations/create-product-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
group: graphql
title: createProductReview mutation
---

The `createProductReview` mutation adds a review for the specified product. Use the [`productReviewRatingsMetadata` query]({{page.baseurl}}/graphql/queries/product-review-ratings-metadata.html) to return a list of rating categories and possible values.

## Syntax

`createProductReview(input: CreateProductReviewInput!): CreateProductReviewOutput!`

## Example usage

In the following example, Roni gives product `WH08` four stars overall, three stars for value, and four stars for quality.

**Request:**

```graphql
mutation {
createProductReview(
input: {
sku: "WH08",
nickname: "Roni",
summary: "Great looking sweatshirt",
text: "This sweatshirt looks and feels great. The zipper sometimes sticks a bit.",
ratings: [
{
id: "NA==",
value_id: "MTk="
}, {
id: "MQ==",
value_id: "NA=="
}, {
id: "Mg==",
value_id: "OA=="
}
]
}
) {
review {
nickname
summary
text
average_rating
ratings_breakdown {
name
value
}
}
}
}
```

**Response:**

```json
{
"data": {
"createProductReview": {
"review": {
"nickname": "Roni",
"summary": "Great looking sweatshirt",
"text": "This sweatshirt looks and feels great. The zipper sometimes sticks a bit.",
"average_rating": 73.33,
"ratings_breakdown": [
{
"name": "Quality",
"value": "4"
},
{
"name": "Value",
"value": "3"
},
{
"name": "Overall",
"value": "4"
}
]
}
}
}
}
```

## Input attributes

The `CreateProductReviewInput` input object defines the product review.

### CreateProductReviewInput attributes {#CreateProductReviewInput}

The `CreateProductReviewInput` object contains the following attributes:

Attribute | Data Type | Description
--- | --- | ---
`nickname` | String! | The customer's nickname. Defaults to the customer name, if logged in
`ratings` | [ProductReviewRatingInput!]! | Ratings details by category. e.g price: 5, quality: 4 etc
`sku` | String! | The SKU of the reviewed product
`summary` | String! | The summary (title) of the review
`text` | String! | The review text.

### ProductReviewRatingInput attributes {#ProductReviewRatingInput}

The `ProductReviewRatingInput` object contains the following attributes:

Attribute | Data Type | Description
--- | --- | ---
`id` | String! | An encoded rating ID
`value_id` | String! | An encoded rating value ID

## Output attributes

The `CreateProductReviewOutput` output object contains the following attribute:

Attribute | Data Type | Description
--- | --- | ---
`review` | ProductReview! | Contains the completed product review

### ProductReview attributes {#ProductReview}

{% include graphql/product-review.md %}
16 changes: 16 additions & 0 deletions src/guides/v2.4/graphql/product/product-interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,10 @@ Attribute | Data type | Description
`price_range` | [PriceRange!](#PriceRange) | A `PriceRange` object, indicating the range of prices for the product
`price_tiers` | [TierPrice] | An array of `TierPrice` objects
`product_links` | [ProductLinksInterface] | An array of [ProductLinks](#ProductLinks) objects
`rating_summary` | Float! | The average of all the ratings given to the product
`related_products` | [ProductInterface] | An array of related products
`review_count` | Int! | The total count of all the reviews given to the product
`reviews(pageSize: Int = 20 currentPage: Int = 1)` | [ProductReviews!](#ProductReviews) | The list of reviews of the product
`short_description` | ComplexTextValue | An object that contains a short description of the product. Its use depends on the store's theme. The object can include simple HTML tags
`sku` | String | A number or code assigned to a product to identify the product, options, price, and manufacturer
`small_image` | [ProductImage](#ProductImage) | An object that contains the URL and label for the small image used on catalog pages
Expand Down Expand Up @@ -153,6 +156,19 @@ Attribute | Data Type | Description
`code` | PriceAdjustmentCodesEnum | One of `tax`, `weee`, or `weee_tax`.
`description` | PriceAdjustmentDescriptionEnum | Indicates whether the entity described by the code attribute is included or excluded from the adjustment.

#### ProductReviews object {#ProductReviews}

`ProductReviews` contains an array of reviews written about the product.

Attribute | Data Type | Description
--- | --- | ---
`items` | [ProductReview]! | An array of product reviews
`page_info` | [SearchResultPageInfo!]({{page.baseurl}}/graphql/queries/products.html#SearchResultPageInfo) | Metadata for pagination rendering

#### ProductReview object {#ProductReview}

{% include graphql/product-review.md %}

#### ProductLinks object {#ProductLinks}

`ProductLinks` contains information about linked products, including the link type and product type of each item.
Expand Down
33 changes: 33 additions & 0 deletions src/guides/v2.4/graphql/queries/customer.md
Original file line number Diff line number Diff line change
Expand Up @@ -501,6 +501,39 @@ Attribute | Data Type | Description

{% include graphql/customer-orders-output.md %}

#### ProductReviews object {#ProductReviews}

`ProductReviews` contains an array of reviews written about the product.

Attribute | Data Type | Description
--- | --- | ---
`items` | [ProductReview]! | An array of product reviews
`page_info` | [SearchResultPageInfo!]({{page.baseurl}}/graphql/queries/products.html#SearchResultPageInfo) | Metadata for pagination rendering

#### ProductReview object {#ProductReview}

{% include graphql/product-review.md %}

### Wishlist attributes {#Wishlist}

Attribute | Data type | Description
--- | --- | ---
`items` | [[WishlistItem](#wishlistitem)] | An array of items in the customer's wish list
`items_count` | Int | The number of items in the wish list
`id` | ID | The unique identifier of the wish list
`sharing_code` | String | An encrypted code that Magento uses to link to the wish list
`updated_at` | String | The time of the last modification to the wish list

#### WishlistItem attributes {#wishlistitem}

Attribute | Data type | Description
--- | --- | ---
`added_at` | String | The time when the customer added the item to the wish list
`description` | String | The customer's comment about this item
`id` | Int | The wish list item ID
`product` | [ProductInterface]({{ page.baseurl }}/graphql/product/product-interface.html) | The ProductInterface contains attributes that are common to all types of products. Note that descriptions may not be available for custom and EAV attributes
`qty` | Float | The quantity of this wish list item

### Store credit attributes

In {{site.data.var.ee}}, the merchant can assign store credit to customers. Magento maintains the history of all changes to the balance of store credit available to the customer. The customer must be logged in to access the store credit history and balance.
Expand Down
155 changes: 155 additions & 0 deletions src/guides/v2.4/graphql/queries/product-review-ratings-metadata.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
---
group: graphql
title: productReviewRatingsMetadata query
---

The `productReviewRatingsMetadata` query returns the active ratings attributes and the values each rating can have. In Luma, these values are one star through five stars.

Use the [`createProductReview` mutation]({{page.baseurl}}/graphql/mutations/create-product-review.html) to add a product review.

## Syntax

`productReviewRatingsMetadata: ProductReviewRatingsMetadata!`

## Example usage

The following query returns the metadata for all active ratings attributes. In this example, the default `Rating` attribute has been renamed to `Overall`, and the `Quality` and `Value` attributes have been enabled.

**Request:**

```graphql
query {
productReviewRatingsMetadata {
items {
id
name
values {
value_id
value
}
}
}
}
```

**Response:**

```json
{
"data": {
"productReviewRatingsMetadata": {
"items": [
{
"id": "NA==",
"name": "Overall",
"values": [
{
"value_id": "MTY=",
"value": "1"
},
{
"value_id": "MTc=",
"value": "2"
},
{
"value_id": "MTg=",
"value": "3"
},
{
"value_id": "MTk=",
"value": "4"
},
{
"value_id": "MjA=",
"value": "5"
}
]
},
{
"id": "MQ==",
"name": "Quality",
"values": [
{
"value_id": "MQ==",
"value": "1"
},
{
"value_id": "Mg==",
"value": "2"
},
{
"value_id": "Mw==",
"value": "3"
},
{
"value_id": "NA==",
"value": "4"
},
{
"value_id": "NQ==",
"value": "5"
}
]
},
{
"id": "Mg==",
"name": "Value",
"values": [
{
"value_id": "Ng==",
"value": "1"
},
{
"value_id": "Nw==",
"value": "2"
},
{
"value_id": "OA==",
"value": "3"
},
{
"value_id": "OQ==",
"value": "4"
},
{
"value_id": "MTA=",
"value": "5"
}
]
}
]
}
}
}
```

## Input attributes

Not applicable

## Output attributes {#Categories}

The `ProductReviewRatingsMetadata` output object contains the `items` object.

Attribute | Data type | Description
--- | --- | ---
`items` | [ProductReviewRatingMetadata!]! | A list of product reviews, sorted by position

### ProductReviewRatingMetadata attributes {#ProductReviewRatingMetadata}

The `ProductReviewRatingMetadata` object contains the following attributes.

Attribute | Data type | Description
--- | --- | ---
`id` | String! | | An encoded rating ID
`name` | String! | The label assigned to an aspect of a product that is being rated, such as quality or price
`values` | [ProductReviewRatingValueMetadata!]! | A list of product review ratings, sorted by position

### ProductReviewRatingValueMetadata attributes {#ProductReviewRatingValueMetadata}

The `ProductReviewRatingValueMetadata` object contains the following attributes.

Attribute | Data type | Description
--- | --- | ---
value | String! | A ratings scale, such as the number of stars awarded
value_id | String! | An encoded rating value ID
Loading