Code examples and such

[industrian]

Type for upvotes/downvotes

{
  "key" : "user-votes",
  "name" : {
    "en" : "User votes"
  },
  "description" : {
    "en" : "Contains definitions for how Customers can interact with Reviews."
  },
  "resourceTypeIds" : [ "review" ],
  "fieldDefinitions" : [ {
    "name" : "upvote",
    "label" : {
      "en" : "This review was helpful."
    },
    "required" : false,
    "type" : {
      "name" : "Set",
      "elementType":{
        "name": "Reference",
        "referenceTypeId": "customer"
      }
    },
    "inputHint" : "SingleLine"
  },
  {
    "name" : "downvote",
    "label" : {
      "en" : "This review was not helpful."
    },
    "required" : false,
    "type" : {
      "name" : "Set",
      "elementType":{
        "name": "Reference",
        "referenceTypeId": "customer"
      }
    },
    "inputHint" : "SingleLine"
  } ]
}

Add Custom Fields to review

{
  "authorName" : "John Doe",
  "title" : "Incredible",
  "text" : "Best product ever",
  "rating" : 5,
  "target" : {
    "typeId" : "product",
    "key" : "6283691"
  },
  "customer":{
    "typeId": "customer",
    "id":"5ab3edcd-9d23-4934-8f48-256805253119"
  },
  "custom":{
    "type":{
"key":"user-votes",
"typeId":"type"
    },
    "fields":{
"upvote":[],
"downvote":[]
    }
  }
}

Add an upvote to a review

{
    "version": {{review-version}},
    "actions": [
        {
            "action" : "setCustomField",
            "name" : "upvote",
            "value": [
  ...existingValues,
  {
    "typeId": "customer",
    "id": "5ab3edcd-9d23-4934-8f48-256805253119"
  }
]
          }
    ]
}

https://docs.commercetools.com/learning-composable-commerce-administrator/extensibility/data-model-extensions

## Expanding existing resources

[Types](/projects/types) are similiar to Attributes defined by Product Types. They allow adding extra fields to most resources within Composable Commerce. For example, you could define the field `shoeSize` for Customers which contains a number value.

[Custom Fields](/projects/custom-fields) refer to the values set for Types on a resource. For example, the Customer setting their `shoeSize` to `10`.

## Adding custom resources

[Custom Objects](/projects/custom-objects) allow you to store namespaced JSON values within your Composable Commerce Project. Any number, string, boolean, array, object, or [common API data type](/types) value can be saved, allowing you to consolidate your data within your Project.

## Extending behavior 

[API Extensions](/projects/api-extensions) run after an API call is made, but before it is processed by Composable Commerce. This makes it useful for synchronous tasks which must be performed _before_ a resource is created or updated.

[Subscriptions](/projects/subscriptions) allow you to create asynchronous background processes which run shortly _after_ resources are created or updated.

## Implementing workflows

[States](/projects/states) allow you to model finite state machines reflecting custom business logic.

# Example use

The following examples demonstrate ideas of how each of these resources could be used to enhance your Composable Commerce Project.

## Add voting to Reviews with Types and Custom Fields

By default, [Reviews](/projects/reviews#review) contain fields for a `rating` and `text`. By extending the Review using Types and Custom Fields, you can add fields for `upvotes` and `downvotes` which contain sets of Customer references.

<code>

After creating this type, values for `upvotes` and `downvotes` could be set  for the Custom Field whenever a Customer upvotes or downvotes a Review.

As the content of the `upvotes` and `downvotes` are returned when you query the Review, you would not need to make multiple calls to retrieve their values. The lengths of the `upvotes` and `downvotes` sets could also be used for sorting the order of Reviews on your frontend.

## Add comments to Reviews with Custom Objects

Sometimes you may want to enable comments and responses to invidual Reviews. While this is possible using Types and Custom Fields, it would be better suited to Custom Objects as multiple related fields are required.

The `container` and `key` of the Custom Object can effectively namespace and identify the Review the comments relate to. Within `value`, you can contain an array of fields to create a list of votable and attributable comments.

{
"container":"review-comments",
"key":"{review-key-or-id}"
"value":[
"customer":{},
"text":"",
"upvotes":[],
"downvotes":[]
]
}

As these fields are not stored within the Review itself, they can also be asynchronously retrieved when necessary. For example, when the user clicks a "Show comments" button.

## Verify Customers with API Extensions

As Customer information is provided by end-users, this unfortunately may be open to abuse. One idea for handling this would be to use an API Extension which runs when a Customer is created or updated. The API Extension could run a small script which:

- Checks if the user has previously been banned.
- Verifies that the email address is from a trusted domain.
- Runs a profanity check on the given fields, such as `firstName` and `lastName`.

As API Extensions run before an API call is received by 

## Send Customers confirmation emails using Subscriptions

When a new customer signs up, or an existing customer changes their email address, their email address is unverified. Ideally, you would send them an email with a link to verify their email address, which would active their account.

By subscribing to the [CustomerCreated](/projects/messages/customer-messages#customer-created) and [CustomerEmailChanged](/projects/messages/customer-messages#customer-email-changed) Messages, you can implement an asynchronous background process which sends these verification emails.

## Implement a review approval process using States

To implement an approval or review process for new Reviews, you could create two States: `to-approve` and `approved` to manage this process. An example of this implementation can be found in our [tutorial](/../tutorials/review-ratings#review-approval-process).

[industrian]

function AddUpvote(reviewID, customerId) {
  const review = // fetch the Review using the reviewID

  const updateAction = {
    version: review.version,
    actions: [
      {
        action: 'setCustomField',
        name: 'upvotes',
        value: [
          ...review.custom.fields.upvotes,
          {
            typeId: 'customer',
            id: customerId,
          },
        ],
      },
    ],
  };

  // TODO: Perform update action
}