A question item that allows the respondent to select one choice from a list of radio buttons or
an optional "other" field. Items can be accessed or created from a Form
. When used in a
quiz, these items are autograded.
// Open a form by ID and add a new multiple choice item. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var item = form.addMultipleChoiceItem(); item.setTitle('Do you prefer cats or dogs?') .setChoices([ item.createChoice('Cats'), item.createChoice('Dogs') ]) .showOtherOption(true);
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 multiple-choice item. |
duplicate() | MultipleChoiceItem | 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 . |
hasOtherOption() | Boolean | Determines whether the item has an "other" option. |
isRequired() | Boolean | Determines whether the respondent must answer the question. |
setChoiceValues(values) | MultipleChoiceItem | Sets the choices for an item from an array of strings. |
setChoices(choices) | MultipleChoiceItem | Sets an array of choices for an item. |
setFeedbackForCorrect(feedback) | MultipleChoiceItem | Sets the feedback to be shown to respondents when they respond correctly to a question. |
setFeedbackForIncorrect(feedback) | MultipleChoiceItem | Sets the feedback to be shown to respondents when they respond incorrectly to a question. |
setHelpText(text) | MultipleChoiceItem | Sets the item's help text (sometimes called description text for layout items like ImageItems , PageBreakItems , and SectionHeaderItems ). |
setPoints(points) | MultipleChoiceItem | Sets the number of points a gradeable item is worth. |
setRequired(enabled) | MultipleChoiceItem | Sets whether the respondent must answer the question. |
setTitle(title) | MultipleChoiceItem | Sets the item's title (sometimes called header text, in the case of a SectionHeaderItem ). |
showOtherOption(enabled) | MultipleChoiceItem | Sets whether the item has an "other" option. |
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 multiple-choice item. Throws an exception if the
response
argument does not match a valid choice for this item, unless showOtherOption(enabled)
is set to true
.
Parameters
Name | Type | Description |
---|---|---|
response | String | a valid answer for this multiple-choice 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
MultipleChoiceItem
— a duplicate of this MultipleChoiceItem
, 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()
hasOtherOption()
Determines whether the item has an "other" option.
Return
Boolean
— true
if the item has an "other" option; false
if not
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
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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
MultipleChoiceItem
— 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
MultipleChoiceItem
— this MultipleChoiceItem
, 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
showOtherOption(enabled)
Sets whether the item has an "other" option. The default for a new CheckboxItem
or
MultipleChoiceItem
is false
.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the item has an "other" option; false if not |
Return
MultipleChoiceItem
— this MultipleChoiceItem
, 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