> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Capturing and Displaying Ratings

## Article: Capturing and Displaying Ratings

## Article Link: https://dev.wix.com/docs/develop-websites/articles/code-tutorials/wix-editor-elements/capturing-and-displaying-ratings.md

## Article Content:

# Velo Tutorial: Capture and Display Ratings

This tutorial shows you how you can capture and display ratings of your items from your visitors. You will set up a Ratings Display element to display the current average rating and the total number of ratings. Then using a Ratings Input element, you'll capture your visitor's rating, calculate the new average rating and total number of ratings, and then update the collection and the Ratings Display element with the new values. 

<div style="text-align:center">

<img src="https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11e10e4f-b84d-4136-a5a9-6109fab0b7d7/2018/10/28/2bc1dcfb-85b8-409f-a630-b706fa40ef8d.png" style="max-width:30vw" />

</div>

You'll need a collection with items you want to let your visitors rate and a page with a dataset connected to that collection. 

This tutorial has 3 parts:

*   [How to set up your collection and your page](#set-up)
*   [Code you can copy and paste onto your page](#the-code)
*   [A detailed explanation of the code](#code-explanation)

## Set up

This section covers what you need to prepare in your collection and what you need to do in your page in the editor.

#### In your collection

1.  Make sure your collection's [permissions](https://support.wix.com/en/article/changing-your-database-collection-permissions) allow visitors to view and add content.
2.  Add 3 new Number fields, for the average rating, number of ratings submitted, and sum of all the ratings submitted. You can leave these fields blank or input starting values. Remember that the average rating must be between 1 and 5.

#### In your page

1.  Set your dataset's [mode](https://support.wix.com/en/article/working-with-dataset-modes-and-collection-permissions) to "Read and Write." This will let your visitors update information in the collection.
2.  Add the following elements:
    1.  A [Ratings Display](https://support.wix.com/en/article/working-with-the-connect-ratings-panel) element connected to the new Number fields in your collection.
    2.  A [Ratings Input](https://support.wix.com/en/article/ratings-input) element your visitors can use to pick a rating for the item. You can use the default setting for the ratings, or define your own. Don't connect it to the dataset.

## The code

This section has 2 parts. The first part shows you how to add the event handler to the Ratings Input element. The second part has the actual code that you can copy and paste onto your page.

#### Add the event handler

An [event handler](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/velo-workspace/code-editor-ide/working-in-the-code-editor.md) adds code that only runs when your visitor performs a certain action. In our code, we used the "onChange" event, so that the rating is saved when our visitor makes their selection in the Ratings Input.

**To add the event handler:**

1.  Select your Ratings Input.
2.  In the [Properties & Events panel](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/velo-workspace/properties-events-panel/about-the-properties-events-panel.md), click the "onChange" event handler.
    
    The code for the event handler is added to the bottom of your page code. The image below shows what it looked like on our page.

    ```js
    $w('#ratingsInput1').onChange((event) => {
        //Add your code for this event here:
    })
    ```
#### Add the code

1.  Copy the code below and paste it into the event handler method above the line that says "//Add your code for this event here:". You can delete that line if you want.

```javascript
 $w("#dataset1").onReady(() => {
  // get the current item from the dataset
  const currentItem = $w("#dataset1").getCurrentItem();

  // get the current average rating, number of ratings, and
  //total ratings for the current dataset item
  const average = currentItem.avg;
  const count = currentItem.numRatings;
  const total = currentItem.totalRatings;

  // get the new rating from the ratings input
  const newRating = $w('#ratingsInput1').value;

  // calculate the new average rating based on the current
  //average and count
  const newAverageLong = (total + newRating) / (count +1);
  // Round the average rating to 1 decimal point
  const newAverageShort = Number.parseFloat(newAverageLong).toFixed(1);

  // set the dataset fields to the new average, total
  // ratings, and number of ratings
  $w('#dataset1').setFieldValues({
   'avg': newAverageShort,
   'totalRatings': total + newRating,
   'numRatings': (count + 1)
  });
  
  // save the dataset fields to the collection
  $w('#dataset1').save()
   .catch((err) => {
    console.log('could not save new rating');
   });
 });
```

2.  Make sure to make these substitutions.
    *   `'#myDataset1'`: The ID of your dataset
    *   `avg`: The field ID of the field in your collection that holds the average rating
    *   `numRatings`: The field ID of the field in your collection that holds the total number of ratings received
    *   `totalRatings`: The field ID of the field in your collection that holds the sum of all ratings received
    *   `'#ratingsInput1'`: The ID of your Dropdown element
3.  Preview your page and test out the Ratings Input element. Watch how the ratings display element updates when you add a rating. 
4.  Go back to the Content Management System (CMS) to see how the average rating and the total number of ratings for that item have been updated in your collection.

## Code explanation 

First we read the current item from the dataset. Then we define variables called `average`, `count` and `total`, and set their values to be the item's current average rating, number of ratings, and the sum of all the ratings.

```js
  const currentItem = $w("#myDataset").getCurrentItem();
  const average = currentItem.averageRating;
  const count = currentItem.numRatings;
```

We define a variable called `newRating` and set its value to be the rating selected by the user in the Ratings Input.

  `const newRating = Number($w('#ratingsInput1').value);`

Next we calculate the updated average rating and save it to a variable called `newAverageLong`. We then round the results to 1 decimal place and assign it to the variable `newAverageShort`.
```js
  const newAverageLong = (total + newRating) / (count + 1);
  const newAverageShort = Number.parseFloat(newAverageLong).toFixed(1);
```

Now we save the new average rating, sum of all the ratings, and total number of ratings to the current item. We include code to deal with errors should they occur.
```js
$w('#dataset1').setFieldValues({
	'avg': newAverageShort,
	'totalRatings': total + newRating,
	'numRatings': (count + 1)
});

$w('#dataset1').save()
	.catch((err) => {
		console.log('could not save new rating');
	});
```