Class FormApp

Allows a script to open an existing Form or create a new one.

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

// Create and open a form.
const newForm = FormApp.create('Form Name');

Properties

Property	Type	Description
`Alignment`	`Alignment`	An enumeration of types of image alignment.
`DestinationType`	`DestinationType`	An enumeration of types of destinations that can store form responses.
`FeedbackType`	`FeedbackType`	An enumeration of types of form `Feedbacks`.
`ItemType`	`ItemType`	An enumeration of types of form `Items`.
`PageNavigationType`	`PageNavigationType`	An enumeration of possible behaviors for navigating pages.
`RatingIconType`	`RatingIconType`	An enumeration of rating icon types `RatingIcons`

Methods

Method	Return type	Brief description
`create(title)`	`Form`	Creates and returns a new `Form`.
`createCheckboxGridValidation()`	`CheckboxGridValidationBuilder`	Returns an instance of a CheckboxGridValidationBuilder which can be used to set validation on a `CheckboxGridItem`.
`createCheckboxValidation()`	`CheckboxValidationBuilder`	Returns an instance of a CheckboxValidationBuilder which can be used to set validation on a `CheckboxItem`.
`createFeedback()`	`QuizFeedbackBuilder`	Returns an instance of a QuizFeedbackBuilder which can be used to set feedback on a gradeable `Item`.
`createGridValidation()`	`GridValidationBuilder`	Returns an instance of a GridValidationBuilder which can be used to set validation on a `GridItem`.
`createParagraphTextValidation()`	`ParagraphTextValidationBuilder`	Returns an instance of a ParagraphTextValidationBuilder which can be used to set validation on a `ParagraphTextItem`.
`createTextValidation()`	`TextValidationBuilder`	Returns an instance of a TextValidationBuilder which can be used to set validation on a `TextItem`.
`getActiveForm()`	`Form`	Returns the form to which the script is container-bound.
`getUi()`	`Ui`	Returns an instance of the form editor's user-interface environment that allows the script to add features like menus, dialogs, and sidebars.
`openById(id)`	`Form`	Returns the `Form` with the specified ID.
`openByUrl(url)`	`Form`	Returns the `Form` with the specified URL.

Detailed documentation

`create(title)`

Creates and returns a new Form. Throws an exception if the given title is null or empty.

// Create and open a form.
const form = FormApp.create('Form Name');

Parameters

Name	Type	Description
`title`	`String`	the name of the new form

Return

Form — the new form

Throws

Error — if the given title is null or empty

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/forms

`createCheckboxGridValidation()`

Returns an instance of a CheckboxGridValidationBuilder which can be used to set validation on a CheckboxGridItem.

Return

CheckboxGridValidationBuilder

`createCheckboxValidation()`

Returns an instance of a CheckboxValidationBuilder which can be used to set validation on a CheckboxItem.

Return

CheckboxValidationBuilder

`createFeedback()`

Returns an instance of a QuizFeedbackBuilder which can be used to set feedback on a gradeable Item.

Return

QuizFeedbackBuilder

`createGridValidation()`

Returns an instance of a GridValidationBuilder which can be used to set validation on a GridItem.

Return

GridValidationBuilder

`createParagraphTextValidation()`

Returns an instance of a ParagraphTextValidationBuilder which can be used to set validation on a ParagraphTextItem.

Return

ParagraphTextValidationBuilder

`createTextValidation()`

Returns an instance of a TextValidationBuilder which can be used to set validation on a TextItem.

Return

TextValidationBuilder

`getActiveForm()`

Returns the form to which the script is container-bound. To interact with forms to which the script is not container-bound, use openById(id) or openByUrl(url) instead.

// Get the form to which this script is bound.
const form = FormApp.getActiveForm();

Return

Form — the form to which the script is bound, or null if the script is not bound to a form

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

`getUi()`

Returns an instance of the form editor's user-interface environment that allows the script to add features like menus, dialogs, and sidebars. A script can only interact with the UI for the current instance of an open form editor (not the view that a respondent sees), and only if the script is bound to the form. For more information, see the guides to menus and dialogs and sidebars.

// Add a custom menu to the active form, including a separator and a sub-menu.
function onOpen(e) {
  FormApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(
          FormApp.getUi()
              .createMenu('My sub-menu')
              .addItem('One sub-menu item', 'mySecondFunction')
              .addItem('Another sub-menu item', 'myThirdFunction'),
          )
      .addToUi();
}

Return

Ui — an instance of this form's user-interface environment

`openById(id)`

Returns the Form with the specified ID. Throws an exception if the ID is invalid or the user does not have permission to open the form.

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

Parameters

Name	Type	Description
`id`	`String`	the ID of the form to open

Return

Form — the form with the given ID

Throws

Error — if the given ID is invalid or the user does not have sufficient permissions

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/forms

`openByUrl(url)`

Returns the Form with the specified URL. Throws an exception if the URL is invalid or the user does not have permission to open the form.

// Open a form by URL.
const form = FormApp.openByUrl(
    'https://docs.google.com/forms/d/1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3/edit',
);

Parameters

Name	Type	Description
`url`	`String`	the URL of the form to open

Return

Form — the form with the given URL

Throws

Error — if the given URL is invalid or the user does not have sufficient permissions

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/forms