RatingItem

A question item that allows the respondent to give a rating. Items can be accessed or created
from a `https://developers.google.com/apps-script/reference/forms/form`. When used in a quiz, these items are graded.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and access its properties.
const existingRatingItem = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
const ratingScaleLevel = existingRatingItem.getRatingScaleLevel();
const ratingIcon = existingRatingItem.getRatingIcon();

// Create a new rating item.
const ratingItem = form.addRatingItem();

// Update the rating item's properties via chaining.
ratingItem.setRatingScaleLevel(7).setRatingIcon(FormApp.RatingIconType.HEART);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/forms/rating-item#createResponse(Integer)` | `https://developers.google.com/apps-script/reference/forms/item-response` | Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this rating item. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#duplicate()` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Creates a copy of this item and appends it to the end of the form. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getGeneralFeedback()` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` | Returns the feedback that is shown to respondents when they respond to a gradeable question. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getHelpText()` | `String` | Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getId()` | `Integer` | Gets the item's unique identifier. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getIndex()` | `Integer` | Gets the index of the item among all the items in the form. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getPoints()` | `Integer` | Returns the point value of a gradeable item. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getRatingIcon()` | `https://developers.google.com/apps-script/reference/forms/rating-icon-type` | Gets the icon chosen for the rating. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getRatingScaleLevel()` | `Integer` | Gets the rating's scale level. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getTitle()` | `String` | Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/rating-item#getType()` | `https://developers.google.com/apps-script/reference/forms/item-type` | Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#isRequired()` | `Boolean` | Determines whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setGeneralFeedback(QuizFeedback)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the feedback to be shown to respondents when they respond to a gradeable question that doesn't have a correct or incorrect answer (ie questions that require manual grading). |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setHelpText(String)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setPoints(Integer)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the number of points a gradeable item is worth. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setRatingIcon(RatingIconType)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the rating's icon. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setRatingScaleLevel(Integer)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the rating's maximum scale level. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setRequired(Boolean)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/rating-item#setTitle(String)` | `https://developers.google.com/apps-script/reference/forms/rating-item#` | Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |

## Detailed documentation

### `createResponse(response)`

Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this rating item.

Throws a scripting exception if the provided `response` is less than `1` or
greater than the value returned by `https://developers.google.com/apps-script/reference/forms/rating-item#getRatingScaleLevel()`.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and create a response for it.
const item = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
const response =item.createResponse(5);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `response` | `Integer` | A value answer for this rating item. |

#### Return


`https://developers.google.com/apps-script/reference/forms/item-response` --- The item response.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `duplicate()`

Creates a copy of this item and appends it to the end of the form.

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- a duplicate of this `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getGeneralFeedback()`

Returns the feedback that is shown to respondents when they respond to a gradeable question.

#### Return


`https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` --- the feedback, if any.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getHelpText()`

Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's help text or description text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getId()`

Gets the item's unique identifier.

#### Return


`Integer` --- the item's ID

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getIndex()`

Gets the index of the item among all the items in the form.

#### Return


`Integer` --- the index of the item

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getPoints()`

Returns the point value of a gradeable item.

#### Return


`Integer` --- the number of points a question is worth.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getRatingIcon()`

Gets the icon chosen for the rating.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and get its rating icon.
const item = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
const ratingIcon = item.getRatingIcon();
```

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-icon-type` --- The rating icon type.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getRatingScaleLevel()`

Gets the rating's scale level.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and get its rating scale level.
const item = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
const ratingScaleLevel = item.getRatingScaleLevel();
```

#### Return


`Integer` --- The rating scale level.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getTitle()`

Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's title or header text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getType()`

Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`.

#### Return


`https://developers.google.com/apps-script/reference/forms/item-type` --- the item's type

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `isRequired()`

Determines whether the respondent must answer the question.

#### Return


`Boolean` --- whether the respondent must answer the question

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setGeneralFeedback(feedback)`

Sets the feedback to be shown to respondents when they respond to a gradeable question that
doesn't have a correct or incorrect answer (ie questions that require manual grading).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `feedback` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback` | the new feedback |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- this `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setHelpText(text)`

Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | the new help text |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- this `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setPoints(points)`

Sets the number of points a gradeable item is worth. The default for new items is 0.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `points` | `Integer` | the number of a points a question item is worth |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- this `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRatingIcon(ratingIcon)`

Sets the rating's icon.

Throws a scripting exception if the rating icon type is invalid.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and set its rating icon.
const item = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
item.setRatingIcon(FormApp.RatingIconType.THUMB_UP);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `ratingIcon` | `https://developers.google.com/apps-script/reference/forms/rating-icon-type` | The rating icon type. |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- This `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining.

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the rating icon type is invalid

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRatingScaleLevel(ratingScaleLevel)`

Sets the rating's maximum scale level. The rating's maximum scale level must be between `3` and `10`, inclusive. A new rating defaults to a rating scale level of `3`.

Throws a scripting exception if the given values are outside the permitted limits.

```javascript
// Open a form by ID
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

// Get an existing rating item and set its rating scale level.
const item = form.getItems(FormApp.ItemType.RATING)[0].asRatingItem();
item.setRatingScaleLevel(7);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `ratingScaleLevel` | `Integer` | The rating scale level. |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- This `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining.

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the rating scale level is invalid

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRequired(enabled)`

Sets whether the respondent must answer the question.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `enabled` | `Boolean` | whether the respondent must answer the question |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- the current item (for chaining)

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setTitle(title)`

Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | the new title or header text |

#### Return


`https://developers.google.com/apps-script/reference/forms/rating-item#` --- this `https://developers.google.com/apps-script/reference/forms/rating-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`