FormApp

Allows a script to open an existing `https://developers.google.com/apps-script/reference/forms/form` or create a new one.

```javascript
// 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` | `https://developers.google.com/apps-script/reference/forms/alignment` | An enumeration of types of image alignment. |
| `DestinationType` | `https://developers.google.com/apps-script/reference/forms/destination-type` | An enumeration of types of destinations that can store form responses. |
| `FeedbackType` | `https://developers.google.com/apps-script/reference/forms/feedback-type` | An enumeration of types of form `https://developers.google.com/apps-script/reference/forms/quiz-feedback`. |
| `ItemType` | `https://developers.google.com/apps-script/reference/forms/item-type` | An enumeration of types of form `https://developers.google.com/apps-script/reference/forms/item`. |
| `PageNavigationType` | `https://developers.google.com/apps-script/reference/forms/page-navigation-type` | An enumeration of possible behaviors for navigating pages. |
| `RatingIconType` | `https://developers.google.com/apps-script/reference/forms/rating-icon-type` | An enumeration of rating icon types `https://developers.google.com/apps-script/reference/forms/rating-icon-type` |

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/forms/form-app#create(String)` | `https://developers.google.com/apps-script/reference/forms/form` | Creates and returns a new `https://developers.google.com/apps-script/reference/forms/form`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#create(String,Boolean)` | `https://developers.google.com/apps-script/reference/forms/form` | Creates and returns a new `https://developers.google.com/apps-script/reference/forms/form` in the requested publish state. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createCheckboxGridValidation()` | `https://developers.google.com/apps-script/reference/forms/checkbox-grid-validation-builder` | Returns an instance of a CheckboxGridValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/checkbox-grid-item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createCheckboxValidation()` | `https://developers.google.com/apps-script/reference/forms/checkbox-validation-builder` | Returns an instance of a CheckboxValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/checkbox-item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createFeedback()` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback-builder` | Returns an instance of a QuizFeedbackBuilder which can be used to set feedback on a gradeable `https://developers.google.com/apps-script/reference/forms/item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createGridValidation()` | `https://developers.google.com/apps-script/reference/forms/grid-validation-builder` | Returns an instance of a GridValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/grid-item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createParagraphTextValidation()` | `https://developers.google.com/apps-script/reference/forms/paragraph-text-validation-builder` | Returns an instance of a ParagraphTextValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/paragraph-text-item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#createTextValidation()` | `https://developers.google.com/apps-script/reference/forms/text-validation-builder` | Returns an instance of a TextValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/text-item`. |
| `https://developers.google.com/apps-script/reference/forms/form-app#getActiveForm()` | `https://developers.google.com/apps-script/reference/forms/form` | Returns the form to which the script is [container-bound](https://developers.google.com/apps-script/scripts_containers). |
| `https://developers.google.com/apps-script/reference/forms/form-app#getUi()` | `https://developers.google.com/apps-script/reference/base/ui.html` | Returns an instance of the form editor's user-interface environment that allows the script to add features like menus, dialogs, and sidebars. |
| `https://developers.google.com/apps-script/reference/forms/form-app#openById(String)` | `https://developers.google.com/apps-script/reference/forms/form` | Returns the `https://developers.google.com/apps-script/reference/forms/form` with the specified ID. |
| `https://developers.google.com/apps-script/reference/forms/form-app#openByUrl(String)` | `https://developers.google.com/apps-script/reference/forms/form` | Returns the `https://developers.google.com/apps-script/reference/forms/form` with the specified URL. |

## Detailed documentation

### `create(title)`

Creates and returns a new `https://developers.google.com/apps-script/reference/forms/form`. Throws an exception if the given title is `null`
or empty.

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

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The name of the new form. |

#### Return


`https://developers.google.com/apps-script/reference/forms/form` --- The new form.

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

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

*** ** * ** ***

### `create(title, isPublished)`

Creates and returns a new `https://developers.google.com/apps-script/reference/forms/form` in the requested publish state. Throws an exception if
the given title is `null` or empty.

```javascript
// Create, publish and open a form.
const form = FormApp.create('Form Name', true);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The name of the new form. |
| `isPublished` | `Boolean` | Whether the form should be published. |

#### Return


`https://developers.google.com/apps-script/reference/forms/form` --- The new form.

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

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

*** ** * ** ***

### `createCheckboxGridValidation()`

Returns an instance of a CheckboxGridValidationBuilder which can be used to set validation on a
`https://developers.google.com/apps-script/reference/forms/checkbox-grid-item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-grid-validation-builder`

*** ** * ** ***

### `createCheckboxValidation()`

Returns an instance of a CheckboxValidationBuilder which can be used to set validation on a
`https://developers.google.com/apps-script/reference/forms/checkbox-item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-validation-builder`

*** ** * ** ***

### `createFeedback()`

Returns an instance of a QuizFeedbackBuilder which can be used to set feedback on a gradeable
`https://developers.google.com/apps-script/reference/forms/item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/quiz-feedback-builder`

*** ** * ** ***

### `createGridValidation()`

Returns an instance of a GridValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/grid-item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/grid-validation-builder`

*** ** * ** ***

### `createParagraphTextValidation()`

Returns an instance of a ParagraphTextValidationBuilder which can be used to set validation on
a `https://developers.google.com/apps-script/reference/forms/paragraph-text-item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/paragraph-text-validation-builder`

*** ** * ** ***

### `createTextValidation()`

Returns an instance of a TextValidationBuilder which can be used to set validation on a `https://developers.google.com/apps-script/reference/forms/text-item`.

#### Return


`https://developers.google.com/apps-script/reference/forms/text-validation-builder`

*** ** * ** ***

### `getActiveForm()`

Returns the form to which the script is [container-bound](https://developers.google.com/apps-script/scripts_containers). To interact with forms to which the
script is not container-bound, use `https://developers.google.com/apps-script/reference/forms/form-app#openById(String)` or `https://developers.google.com/apps-script/reference/forms/form-app#openByUrl(String)`
instead.

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

#### Return


`https://developers.google.com/apps-script/reference/forms/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://developers.google.com/apps-script/concepts/scopes#setting_explicit_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](https://developers.google.com/apps-script/scripts_containers) to the form. For more
information, see the guides to [menus](https://developers.google.com/apps-script/guides/menus) and [dialogs and sidebars](https://developers.google.com/apps-script/guides/dialogs).

```javascript
// 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


`https://developers.google.com/apps-script/reference/base/ui.html` --- an instance of this form's user-interface environment

*** ** * ** ***

### `openById(id)`

Returns the `https://developers.google.com/apps-script/reference/forms/form` with the specified ID. Throws an exception if the ID is invalid or the
user does not have permission to open the form.

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

#### Parameters

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

#### Return


`https://developers.google.com/apps-script/reference/forms/form` --- the form with the given ID

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

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

*** ** * ** ***

### `openByUrl(url)`

Returns the `https://developers.google.com/apps-script/reference/forms/form` with the specified URL. Throws an exception if the URL is invalid or
the user does not have permission to open the form.

```javascript
// 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


`https://developers.google.com/apps-script/reference/forms/form` --- the form with the given URL

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

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