Class FormApp

FormApp

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

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

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

Properties

PropertyTypeDescription
AlignmentAlignmentAn enumeration of types of image alignment.
DestinationTypeDestinationTypeAn enumeration of types of destinations that can store form responses.
FeedbackTypeFeedbackTypeAn enumeration of types of form Feedbacks.
ItemTypeItemTypeAn enumeration of types of form Items.
PageNavigationTypePageNavigationTypeAn enumeration of possible behaviors for navigating pages.

Methods

MethodReturn typeBrief description
create(title)FormCreates and returns a new Form.
createCheckboxGridValidation()CheckboxGridValidationBuilderReturns an instance of a CheckboxGridValidationBuilder which can be used to set validation on a CheckboxGridItem.
createCheckboxValidation()CheckboxValidationBuilderReturns an instance of a CheckboxValidationBuilder which can be used to set validation on a CheckboxItem.
createFeedback()QuizFeedbackBuilderReturns an instance of a QuizFeedbackBuilder which can be used to set feedback on a gradeable Item.
createGridValidation()GridValidationBuilderReturns an instance of a GridValidationBuilder which can be used to set validation on a GridItem.
createParagraphTextValidation()ParagraphTextValidationBuilderReturns an instance of a ParagraphTextValidationBuilder which can be used to set validation on a ParagraphTextItem.
createTextValidation()TextValidationBuilderReturns an instance of a TextValidationBuilder which can be used to set validation on a TextItem.
getActiveForm()FormReturns the form to which the script is container-bound.
getUi()UiReturns an instance of the form editor's user-interface environment that allows the script to add features like menus, dialogs, and sidebars.
openById(id)FormReturns the Form with the specified ID.
openByUrl(url)FormReturns 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.
var form = FormApp.create('Form Name');

Parameters

NameTypeDescription
titleStringthe 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.
var 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.
var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');

Parameters

NameTypeDescription
idStringthe 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.
var form = FormApp.openByUrl(
    'https://docs.google.com/forms/d/1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3/edit'
    );

Parameters

NameTypeDescription
urlStringthe 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