A question item that allows the respondent to select one choice from a drop-down list. Items can
be accessed or created from a Form
.
// Open a form by ID and add a new list item. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var item = form.addListItem(); item.setTitle('Do you prefer cats or dogs?') .setChoices([ item.createChoice('Cats'), item.createChoice('Dogs') ]);
Methods
Method | Return type | Brief description |
---|---|---|
createChoice(value) | Choice | Creates a new choice. |
createChoice(value, isCorrect) | Choice | Creates a new choice. |
createChoice(value, navigationItem) | Choice | Creates a new choice with a page-navigation option that jumps to a given page-break item. |
createChoice(value, navigationType) | Choice | Creates a new choice with a page-navigation option. |
createResponse(response) | ItemResponse | Creates a new ItemResponse for this list item. |
duplicate() | ListItem | Creates a copy of this item and appends it to the end of the form. |
getChoices() | Choice[] | Gets all choices for an item. |
getFeedbackForCorrect() | QuizFeedback | Returns the feedback that is shown to respondents when they respond correctly to a question. |
getFeedbackForIncorrect() | QuizFeedback | Returns the feedback that is shown to respondents when they respond incorrectly to a question. |
getHelpText() | String | Gets the item's help text (sometimes called description text for layout items like ImageItems , PageBreakItems , and SectionHeaderItems ). |
getId() | Integer | Gets the item's unique identifier. |
getIndex() | Integer | Gets the index of the item among all the items in the form. |
getPoints() | Integer | Returns the point value of a gradeable item. |
getTitle() | String | Gets the item's title (sometimes called header text, in the case of a SectionHeaderItem ). |
getType() | ItemType | Gets the item's type, represented as an ItemType . |
isRequired() | Boolean | Determines whether the respondent must answer the question. |
setChoiceValues(values) | ListItem | Sets the choices for an item from an array of strings. |
setChoices(choices) | ListItem | Sets an array of choices for an item. |
setFeedbackForCorrect(feedback) | ListItem | Sets the feedback to be shown to respondents when they respond correctly to a question. |
setFeedbackForIncorrect(feedback) | ListItem | Sets the feedback to be shown to respondents when they respond incorrectly to a question. |
setHelpText(text) | ListItem | Sets the item's help text (sometimes called description text for layout items like ImageItems , PageBreakItems , and SectionHeaderItems ). |
setPoints(points) | ListItem | Sets the number of points a gradeable item is worth. |
setRequired(enabled) | ListItem | Sets whether the respondent must answer the question. |
setTitle(title) | ListItem | Sets the item's title (sometimes called header text, in the case of a SectionHeaderItem ). |
Detailed documentation
createChoice(value)
Creates a new choice.
Parameters
Name | Type | Description |
---|---|---|
value | String | the choice's value, which respondents see as a label when viewing the form |
Return
Choice
— the new choice
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
createChoice(value, isCorrect)
Creates a new choice.
Parameters
Name | Type | Description |
---|---|---|
value | String | the choice's value, which respondents see as a label when viewing the form |
isCorrect | Boolean | whether the choice is a correct answer |
Return
Choice
— the new choice
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
createChoice(value, navigationItem)
Creates a new choice with a page-navigation option that jumps to a given page-break item. This
is equivalent to createChoice(value, navigationType)
with navigationType
set to FormApp.PageNavigationType.GO_TO_PAGE
. Choices that use page
navigation cannot be combined in the same item with choices that do not use page navigation.
The page navigation occurs after the respondent completes a page that contains the option, and only if the respondent chose that option. If the respondent chose multiple options with page-navigation instructions on the same page, only the last navigation option has any effect. Page navigation also has no effect on the last page of a form.
Parameters
Name | Type | Description |
---|---|---|
value | String | the choice's value, which respondents see as a label when viewing the form |
navigationItem | PageBreakItem | the item to navigate to |
Return
Choice
— the new choice
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
createResponse(response)
Creates a new ItemResponse
for this list item. Throws an exception if the response
argument does not match a valid choice for this item.
Parameters
Name | Type | Description |
---|---|---|
response | String | a valid answer for this list item |
Return
ItemResponse
— the item response
Authorization
Scripts that use this method require authorization with one or more of the following 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
ListItem
— a duplicate of this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getChoices()
getFeedbackForCorrect()
Returns the feedback that is shown to respondents when they respond correctly to a question.
Return
QuizFeedback
— the feedback, if any.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getFeedbackForIncorrect()
Returns the feedback that is shown to respondents when they respond incorrectly to a question.
Return
QuizFeedback
— the feedback, if any.
Authorization
Scripts that use this method require authorization with one or more of the following 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 ImageItems
, PageBreakItems
, and SectionHeaderItems
).
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://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://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://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://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 SectionHeaderItem
).
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://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getType()
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://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setChoiceValues(values)
Sets the choices for an item from an array of strings. Throws an exception if the given array is empty.
// Open a form by ID and add a new list item. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var item = form.addListItem(); item.setTitle('Do you prefer cats or dogs?'); item.setChoiceValues(['Dogs', 'Cats']);
Parameters
Name | Type | Description |
---|---|---|
values | String[] | the array of choice values, which respondents see as labels when viewing the form |
Return
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setChoices(choices)
Sets an array of choices for an item. Throws an exception if the given array is empty or
contains a null
element.
// Open a form by ID and add a new list item. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var item = form.addListItem(); item.setTitle('Do you prefer cats or dogs?') item.setChoices([ item.createChoice('Cats'), item.createChoice('Dogs') ]);
Parameters
Name | Type | Description |
---|---|---|
choices | Choice[] | an array of choices |
Return
ListItem
— this ListItem
, for chaining
Throws
Error
— if the given array is null
, empty, or contains a null
element
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setFeedbackForCorrect(feedback)
Sets the feedback to be shown to respondents when they respond correctly to a question.
// Open a form by ID and add a new list item. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var item = form.addListItem(); item.setTitle('Do you prefer cats or dogs?'); // Set "Dogs" as the correct answer to this question. item.setChoices([ item.createChoice('Dogs', true), item.createChoice('Cats', false)]); // Add feedback which will be shown for correct responses; ie "Dogs". item.setFeedbackForCorrect( FormApp.createFeedback().setDisplayText("Dogs rule, cats drool.").build());
Parameters
Name | Type | Description |
---|---|---|
feedback | QuizFeedback | the new feedback. A null value will clear the feedback. |
Return
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setFeedbackForIncorrect(feedback)
Sets the feedback to be shown to respondents when they respond incorrectly to a question.
Parameters
Name | Type | Description |
---|---|---|
feedback | QuizFeedback | the new feedback |
Return
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following 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 ImageItems
, PageBreakItems
, and SectionHeaderItems
).
Parameters
Name | Type | Description |
---|---|---|
text | String | the new help text |
Return
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following 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
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following 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
ListItem
— the current item (for chaining)
Authorization
Scripts that use this method require authorization with one or more of the following 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 SectionHeaderItem
).
Parameters
Name | Type | Description |
---|---|---|
title | String | the new title or header text |
Return
ListItem
— this ListItem
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms