Class Form

A form that contains overall properties (such as title, settings, and where responses are stored) and items (which includes question items like checkboxes and layout items like page breaks). Forms can be accessed or created from FormApp.

 // Open a form by ID and create a new spreadsheet.
 var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
 var ss = SpreadsheetApp.create('Spreadsheet Name');

 // Update form properties via chaining.
 form.setTitle('Form Name')
     .setDescription('Description of form')
     .setConfirmationMessage('Thanks for responding!')
     .setAllowResponseEdits(true)
     .setAcceptingResponses(false);

 // Update the form's response destination.
 form.setDestination(FormApp.DestinationType.SPREADSHEET, ss.getId());

Methods

Method	Return type	Brief description
`addCheckboxItem()`	`CheckboxItem`	Appends a new question item that allows the respondent to select one or more checkboxes, as well as an optional "other" field.
`addDateItem()`	`DateItem`	Appends a new question item that allows the respondent to indicate a date.
`addDateTimeItem()`	`DateTimeItem`	Appends a new question item that allows the respondent to indicate a date and time.
`addDurationItem()`	`DurationItem`	Appends a new question item that allows the respondent to indicate a length of time.
`addEditor(emailAddress)`	`Form`	Adds the given user to the list of editors for the `Form`.
`addEditor(user)`	`Form`	Adds the given user to the list of editors for the `Form`.
`addEditors(emailAddresses)`	`Form`	Adds the given array of users to the list of editors for the `Form`.
`addGridItem()`	`GridItem`	Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select one choice per row from a sequence of radio buttons.
`addImageItem()`	`ImageItem`	Appends a new layout item that displays an image.
`addListItem()`	`ListItem`	Appends a new question item that allows the respondent to select one choice from a drop-down list.
`addMultipleChoiceItem()`	`MultipleChoiceItem`	Appends a new question item that allows the respondent to select one choice from a list of radio buttons or an optional "other" field.
`addPageBreakItem()`	`PageBreakItem`	Appends a new layout item that marks the start of a page.
`addParagraphTextItem()`	`ParagraphTextItem`	Appends a new question item that allows the respondent to enter a block of text.
`addScaleItem()`	`ScaleItem`	Appends a new question item that allows the respondent to choose one option from a numbered sequence of radio buttons.
`addSectionHeaderItem()`	`SectionHeaderItem`	Appends a new layout item that visually indicates the start of a section.
`addTextItem()`	`TextItem`	Appends a new question item that allows the respondent to enter a single line of text.
`addTimeItem()`	`TimeItem`	Appends a new question item that allows the respondent to indicate a time of day.
`addVideoItem()`	`VideoItem`	Appends a new layout item that displays a video.
`canEditResponse()`	`Boolean`	Determines whether the form displays a link to edit a response after submitting it.
`collectsEmail()`	`Boolean`	Determines whether the form collects respondents' email addresses.
`createResponse()`	`FormResponse`	Creates a new response to the form.
`deleteAllResponses()`	`Form`	Deletes all submitted responses from the form's response store.
`deleteItem(index)`	`void`	Deletes the item at a given index among all the items in the form.
`deleteItem(item)`	`void`	Deletes the given item.
`getConfirmationMessage()`	`String`	Gets the form's confirmation message.
`getCustomClosedFormMessage()`	`String`	Gets the custom message that will be displayed if the form is not accepting responses, or an empty string if no custom message has been set.
`getDescription()`	`String`	Gets the form's description.
`getDestinationId()`	`String`	Gets the ID of the form's response destination.
`getDestinationType()`	`DestinationType`	Gets the type of the form's response destination.
`getEditUrl()`	`String`	Gets the URL that can be used to access the form's edit mode.
`getEditors()`	`User[]`	Gets the list of editors for this `Form`.
`getId()`	`String`	Gets the ID of the form.
`getItemById(id)`	`Item`	Gets the item with a given ID.
`getItems()`	`Item[]`	Gets an array of all items in the form.
`getItems(itemType)`	`Item[]`	Gets an array of all items of a given type.
`getPublishedUrl()`	`String`	Gets the URL that can be used to respond to the form.
`getResponse(responseId)`	`FormResponse`	Gets a single form response based on its response ID.
`getResponses()`	`FormResponse[]`	Gets an array of all of the form's responses.
`getResponses(timestamp)`	`FormResponse[]`	Gets an array of all of the form's responses after a given date and time.
`getShuffleQuestions()`	`Boolean`	Determines whether the order of the questions on each page of the form is randomized.
`getSummaryUrl()`	`String`	Gets the URL that can be used to view a summary of the form's responses.
`getTitle()`	`String`	Gets the form's title.
`hasLimitOneResponsePerUser()`	`Boolean`	Determines whether the form allows only one response per respondent.
`hasProgressBar()`	`Boolean`	Determines whether the form displays a progress bar.
`hasRespondAgainLink()`	`Boolean`	Determines whether the form displays a link to submit another response after a respondent completes the form.
`isAcceptingResponses()`	`Boolean`	Determines whether the form is currently accepting responses.
`isPublishingSummary()`	`Boolean`	Determines whether the form displays a link to view a summary of responses after a respondent completes the form.
`moveItem(from, to)`	`Item`	Moves an item at a given index among all the items in the form to another given index.
`moveItem(item, toIndex)`	`Item`	Moves a given item to an given index among all the items in the form.
`removeDestination()`	`Form`	Unlinks the form from its current response destination.
`removeEditor(emailAddress)`	`Form`	Removes the given user from the list of editors for the `Form`.
`removeEditor(user)`	`Form`	Removes the given user from the list of editors for the `Form`.
`requiresLogin()`	`Boolean`	Determines whether the form requires respondents to log in to an account in the same domain or a subdomain before responding.
`setAcceptingResponses(enabled)`	`Form`	Sets whether the form is currently accepting responses.
`setAllowResponseEdits(enabled)`	`Form`	Sets whether the form displays a link to edit a response after submitting it.
`setCollectEmail(collect)`	`Form`	Sets whether the form collects respondents' email addresses.
`setConfirmationMessage(message)`	`Form`	Sets the form's confirmation message.
`setCustomClosedFormMessage(message)`	`Form`	Sets the message to display if the form is not accepting responses.
`setDescription(description)`	`Form`	Sets the form's description.
`setDestination(type, id)`	`Form`	Sets the destination where form responses are saved.
`setLimitOneResponsePerUser(enabled)`	`Form`	Sets whether the form allows only one response per respondent.
`setProgressBar(enabled)`	`Form`	Sets whether the form has a progress bar.
`setPublishingSummary(enabled)`	`Form`	Sets whether the form displays a link to view a summary of responses after a respondent submits the form.
`setRequireLogin(requireLogin)`	`Form`	Sets whether the form requires respondents to log in to an account in the same domain or a subdomain before responding.
`setShowLinkToRespondAgain(enabled)`	`Form`	Sets whether the form displays a link to submit another response after a respondent completes the form.
`setShuffleQuestions(shuffle)`	`Form`	Sets whether the order of the questions on each page of the form is randomized.
`setTitle(title)`	`Form`	Sets the form's title.
`shortenFormUrl(url)`	`String`	Converts a long URL for a form to a short URL.

Detailed documentation

`addCheckboxItem()`

Appends a new question item that allows the respondent to select one or more checkboxes, as well as an optional "other" field.

Return

CheckboxItem — the newly created item

`addDateItem()`

Appends a new question item that allows the respondent to indicate a date.

Return

DateItem — the newly created item

`addDateTimeItem()`

Appends a new question item that allows the respondent to indicate a date and time.

Return

DateTimeItem — the newly created item

`addDurationItem()`

Appends a new question item that allows the respondent to indicate a length of time.

Return

DurationItem — the newly created item

`addEditor(emailAddress)`

Adds the given user to the list of editors for the Form. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

Name	Type	Description
`emailAddress`	`String`	the email address of the user to add

Return

Form — this Form, for chaining

`addEditor(user)`

Adds the given user to the list of editors for the Form. If the user was already on the list of viewers, this method promotes the user out of the list of viewers.

Parameters

Name	Type	Description
`user`	`User`	a representation of the user to add

Return

Form — this Form, for chaining

`addEditors(emailAddresses)`

Adds the given array of users to the list of editors for the Form. If any of the users were already on the list of viewers, this method promotes them out of the list of viewers.

Parameters

Name	Type	Description
`emailAddresses`	`String[]`	an array of email addresses of the users to add

Return

Form — this Form, for chaining

`addGridItem()`

Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select one choice per row from a sequence of radio buttons.

Return

GridItem — the newly created item

`addImageItem()`

Appends a new layout item that displays an image.

Return

ImageItem — the newly created item

`addListItem()`

Appends a new question item that allows the respondent to select one choice from a drop-down list.

Return

ListItem — the newly created item

`addMultipleChoiceItem()`

Appends a new question item that allows the respondent to select one choice from a list of radio buttons or an optional "other" field.

Return

MultipleChoiceItem — the newly created item

`addPageBreakItem()`

Appends a new layout item that marks the start of a page.

Return

PageBreakItem — the newly created item

`addParagraphTextItem()`

Appends a new question item that allows the respondent to enter a block of text.

Return

ParagraphTextItem — the newly created item

`addScaleItem()`

Appends a new question item that allows the respondent to choose one option from a numbered sequence of radio buttons.

Return

ScaleItem — the newly created item

`addSectionHeaderItem()`

Appends a new layout item that visually indicates the start of a section.

Return

SectionHeaderItem — the newly created item

`addTextItem()`

Appends a new question item that allows the respondent to enter a single line of text.

Return

TextItem — the newly created item

`addTimeItem()`

Appends a new question item that allows the respondent to indicate a time of day.

Return

TimeItem — the newly created item

`addVideoItem()`

Appends a new layout item that displays a video.

Return

VideoItem — the newly created item

`canEditResponse()`

Determines whether the form displays a link to edit a response after submitting it.

Regardless of this setting, the method FormResponse.getEditResponseUrl() allows a script author who has edit access to the form to generate a URL that can be used to edit a response.

Return

Boolean — true if the form displays an "Edit your response" link; false if not

`collectsEmail()`

Determines whether the form collects respondents' email addresses.

This feature is available only for forms created by users of Google Apps for Business, Google Apps for Education, or Google Apps for Your Domain. Email addresses for other types of Google accounts cannot be collected.

Return

Boolean — true if the form collects email addresses; false if not

`createResponse()`

Creates a new response to the form. To answer a question item, create an ItemResponse from the item, then attach it to this form response by calling FormResponse.withItemResponse(response). To save the assembled response, call FormResponse.submit().

Return

FormResponse — the newly created form response

`deleteAllResponses()`

Deletes all submitted responses from the form's response store. This method does not delete copies of responses stored in an external response destination (like a spreadsheet), but does clear the form's summary view.

Return

Form — this Form, for chaining

`deleteItem(index)`

Deletes the item at a given index among all the items in the form. Throws a scripting exception if no item exists at the given index.

Parameters

Name	Type	Description
`index`	`Integer`	the index of the item among all the items in the form

`deleteItem(item)`

Deletes the given item. Throws a scripting exception if the item has already been deleted.

Parameters

Name	Type	Description
`item`	`Item`	the item to be deleted

`getConfirmationMessage()`

Gets the form's confirmation message.

Return

String — the form's confirmation message

`getCustomClosedFormMessage()`

Gets the custom message that will be displayed if the form is not accepting responses, or an empty string if no custom message has been set.

Return

String — the custom message that will be displayed if the form is not accepting responses, or an empty string if no custom message has been set

`getDescription()`

Gets the form's description.

Return

String — the form's description

`getDestinationId()`

Gets the ID of the form's response destination.

Return

String — the ID of the form's response destination

`getDestinationType()`

Gets the type of the form's response destination.

Return

DestinationType — the type of the form's response destination

`getEditUrl()`

Gets the URL that can be used to access the form's edit mode.

Return

String — the URL to edit the form

`getEditors()`

Gets the list of editors for this Form. If the user who executes the script does not have edit access to the Form, this method throws an exception.

Return

User[] — an array of users with edit permission

`getId()`

Gets the ID of the form.

Return

String — the ID of the form

`getItemById(id)`

Gets the item with a given ID. Returns null if the ID does not correspond to an item in the form.

Parameters

Name	Type	Description
`id`	`Integer`	the item's ID

Return

Item — the item with the given ID, or null if the item does not exist in the form

`getItems()`

Gets an array of all items in the form.

Return

Item[] — an array of all items in the form

`getItems(itemType)`

Gets an array of all items of a given type.

Parameters

Name	Type	Description
`itemType`	`ItemType`	the type of items to retrieve

Return

Item[] — an array of all items of that type

`getPublishedUrl()`

Gets the URL that can be used to respond to the form.

Return

String — the URL to respond to the form

`getResponse(responseId)`

Gets a single form response based on its response ID. Response IDs can be retrieved from FormResponse.getId().

Parameters

Name	Type	Description
`responseId`	`String`	the ID for the form response

Return

FormResponse — the form response

`getResponses()`

Gets an array of all of the form's responses.

Return

FormResponse[] — an array of all of the form's responses

`getResponses(timestamp)`

Gets an array of all of the form's responses after a given date and time.

Parameters

Name	Type	Description
`timestamp`	`Date`	the earliest date and time for which form responses should be returned

Return

FormResponse[] — the list of form responses

`getShuffleQuestions()`

Determines whether the order of the questions on each page of the form is randomized.

Return

Boolean — true if the order of the questions on each page of the form is randomized; false if not

`getSummaryUrl()`

Gets the URL that can be used to view a summary of the form's responses. Unless setPublishingSummary(enabled) is set to true, only users with edit permission to the form will be able to access the URL.

Return

String — the URL to view a summary of responses

`getTitle()`

Gets the form's title.

Return

String — the form's title

`hasLimitOneResponsePerUser()`

Determines whether the form allows only one response per respondent. If the value is true, the script cannot submit form responses at all.

Return

Boolean — true if the form allows only one response per respondent; false if not

`hasProgressBar()`

Determines whether the form displays a progress bar.

Return

Boolean — true if the form displays a progress bar; false if not

`hasRespondAgainLink()`

Determines whether the form displays a link to submit another response after a respondent completes the form.

Return

Boolean — true if the form displays a "Submit another response" link; false if not

`isAcceptingResponses()`

Determines whether the form is currently accepting responses.

Return

Boolean — true if the form is accepting responses; false if not

`isPublishingSummary()`

Determines whether the form displays a link to view a summary of responses after a respondent completes the form.

Return

Boolean — true if the form displays a "See previous responses" link; false if not

`moveItem(from, to)`

Moves an item at a given index among all the items in the form to another given index. Throws a scripting exception if the to index is out of bounds.

Parameters

Name	Type	Description
`from`	`Integer`	the current index of the item among all the items in the form
`to`	`Integer`	the new index for the item among all the items in the form

Return

Item — the item that was moved

`moveItem(item, toIndex)`

Moves a given item to an given index among all the items in the form. Throws a scripting exception if the given index is out of bounds.

Parameters

Name	Type	Description
`item`	`Item`	the item to move
`toIndex`	`Integer`	the new index for the item among all the items in the form

Return

Item — the item that was moved

`removeDestination()`

Unlinks the form from its current response destination. The unlinked former destination still retains a copy of all previous responses. All forms, including those that do not have a destination set explicitly, save a copy of responses in the form's response store. If the form does not currently have a response destination, this method has no effect.

Return

Form — this Form, for chaining

`removeEditor(emailAddress)`

Removes the given user from the list of editors for the Form. This method does not block users from accessing the Form if they belong to a class of users who have general access — for example, if the Form is shared with the user's entire domain.

Parameters

Name	Type	Description
`emailAddress`	`String`	the email address of the user to remove

Return

Form — this Form, for chaining

`removeEditor(user)`

Parameters

Name	Type	Description
`user`	`User`	a representation of the user to remove

Return

Form — this Form, for chaining

`requiresLogin()`

Determines whether the form requires respondents to log in to an account in the same domain or a subdomain before responding.

Return

Boolean — true if the form requires users to log in; false if not

`setAcceptingResponses(enabled)`

Sets whether the form is currently accepting responses. The default for new forms is true.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should accept responses; `false` if not

Return

Form — this Form, for chaining

`setAllowResponseEdits(enabled)`

Sets whether the form displays a link to edit a response after submitting it. The default for new forms is false.

Regardless of this setting, the method FormResponse.getEditResponseUrl() allows a script author who has edit permission to the form to generate a URL that can be used to edit a response.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should display an "Edit your response" link; `false` if not

Return

Form — this Form, for chaining

`setCollectEmail(collect)`

Sets whether the form collects respondents' email addresses. The default for new forms is false. As a side effect, setting this property to true also sets setRequireLogin(requireLogin) to true.

Parameters

Name	Type	Description
`collect`	`Boolean`	`true` if the form should collect email addresses; `false` if not

Return

Form — this Form, for chaining

`setConfirmationMessage(message)`

Sets the form's confirmation message.

Parameters

Name	Type	Description
`message`	`String`	the form's new confirmation message

Return

Form — this Form, for chaining

`setCustomClosedFormMessage(message)`

Sets the message to display if the form is not accepting responses. If no message is set, the form will use a default message.

Parameters

Name	Type	Description
`message`	`String`	the message to display if the form is not accepting responses

Return

Form — this Form, for chaining

`setDescription(description)`

Sets the form's description.

Parameters

Name	Type	Description
`description`	`String`	the form's new description

Return

Form — this Form, for chaining

`setDestination(type, id)`

Sets the destination where form responses are saved. All forms, including those that do not have a destination set explicitly, save a copy of responses in the form's response store.

Parameters

Name	Type	Description
`type`	`DestinationType`	the type of the form's response destination
`id`	`String`	the ID of the form's response destination

Return

Form — this Form, for chaining

`setLimitOneResponsePerUser(enabled)`

Sets whether the form allows only one response per respondent. The default for new forms is false. If the value is set to true, the script cannot submit form responses at all.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should allow only one response per respondent; `false` if not

Return

Form — this Form, for chaining

`setProgressBar(enabled)`

Sets whether the form has a progress bar. The default for new forms is false.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should display a progress bar; `false` if not

Return

Form — this Form, for chaining

`setPublishingSummary(enabled)`

Sets whether the form displays a link to view a summary of responses after a respondent submits the form. The default for new forms is false.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should display a "See previous responses" link; `false` if not

Return

Form — this Form, for chaining

`setRequireLogin(requireLogin)`

Sets whether the form requires respondents to log in to an account in the same domain or a subdomain before responding. The default for new forms is false unless a domain administrator changes the default.

This feature is available only for forms created by users of Google Apps for Business, Google Apps for Education, or Google Apps for Your Domain. Users of other types of Google accounts cannot be required to log in. This method throws a scripting exception for forms created with other Google accounts or if it is set to false while setCollectEmail(collect) is set to true.

Parameters

Name	Type	Description
`requireLogin`	`Boolean`	`true` if the form requires users to log in; `false` if not

Return

Form — the current form (for chaining)

`setShowLinkToRespondAgain(enabled)`

Sets whether the form displays a link to submit another response after a respondent completes the form. The default for new forms is true.

Parameters

Name	Type	Description
`enabled`	`Boolean`	`true` if the form should display a "Submit another response" link; `false` if not

Return

Form — this Form, for chaining

`setShuffleQuestions(shuffle)`

Sets whether the order of the questions on each page of the form is randomized.

Parameters

Name	Type	Description
`shuffle`	`Boolean`	`true` if the order of the questions on each page of the form should be randomized; `false` if not

Return

Form — this Form, for chaining

`setTitle(title)`

Sets the form's title.

Parameters

Name	Type	Description
`title`	`String`	the form's new title

Return

Form — this Form, for chaining

`shortenFormUrl(url)`

Converts a long URL for a form to a short URL. Throws an exception if the long URL does not belong to Google Forms.

Parameters

Name	Type	Description
`url`	`String`

Return

String — a URL in the form http://goo.gl/forms/1234

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated February 26, 2015.