TextInput

A input field widget that accepts text input.

Supports form submission validation. When `https://developers.google.com/apps-script/reference/card-service/action#setAllWidgetsAreRequired(Boolean)` is set to
`true` or this widget is specified through `https://developers.google.com/apps-script/reference/card-service/action#addRequiredWidget(String)`, the submission
action is blocked unless a value is entered.

Available for Google Workspace add-ons and Google Chat apps.

```javascript
const textInput = CardService.newTextInput()
                      .setFieldName('text_input_form_input_key')
                      .setTitle('Text input title')
                      .setHint('Text input hint');
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/text-input#addEventAction(EventAction)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Adds the event action that can be performed on the widget. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setFieldName(String)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the key that identifies this text input in the event object that is generated when there is a UI interaction. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setHint(String)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets a hint for the text input. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setHostAppDataSource(HostAppDataSource)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets a data source from Google Workspace applications. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setId(String)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Sets the unique ID assigned that's used to identify the widget to be mutated. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setInputMode(TextInputMode)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets whether this text input field supports variable insertion. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setMultiline(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets whether the input text shows on one line or multiple lines. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setOnChangeAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets an action to be performed whenever the text input changes. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setSuggestions(Suggestions)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the suggestions for autocompletion in the text field. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setSuggestionsAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the callback action to fetch suggestions based on user input for autocompletion. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setTitle(String)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the title to be shown above the input field. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setValidation(Validation)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the validation rule for this widget. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setValue(String)` | `https://developers.google.com/apps-script/reference/card-service/text-input#` | Sets the pre-filled value to be set in the input field. |
| `https://developers.google.com/apps-script/reference/card-service/text-input#setVisibility(Visibility)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Sets the visibility of the widget. |

## Detailed documentation

### `addEventAction(eventAction)`

Adds the event action that can be performed on the widget.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `eventAction` | `https://developers.google.com/apps-script/reference/card-service/event-action` | The `https://developers.google.com/apps-script/reference/card-service/event-action` to be added. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/widget` --- The Object, for chaining.

*** ** * ** ***

### `setFieldName(fieldName)`

Sets the key that identifies this text input in the event object that is generated when there
is a UI interaction. Not visible to the user. Required, must be unique.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `fieldName` | `String` | The key that is used to identify this input. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setHint(hint)`

Sets a hint for the text input. Used to give the user extra guidance on what to input. For
example, a hint could describe formatting ("xxx-xxx-xxxx") for a phone number field.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `hint` | `String` | The text hint to display below the input field. This text is always visible. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setHostAppDataSource(hostAppDataSource)`

Sets a data source from Google Workspace applications. Currently supports users and Chat
spaces.

Only available for Google Workspace add-ons that extend Google Workspace Studio.

```javascript
const workflowDataSource =
    CardService.newWorkflowDataSource().setIncludeVariables(true);

const hostAppDataSource =
    CardService.newHostAppDataSource().setWorkflowDataSource(workflowDataSource);

const textInput = CardService.newTextInput()
                      .setFieldName('text_input_form_input_key')
                      .setTitle('Text input title')
                      .setHint('Text input hint')
                      .setHostAppDataSource(hostAppDataSource);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `hostAppDataSource` | `https://developers.google.com/apps-script/reference/card-service/host-app-data-source` | The data source. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setId(id)`

Sets the unique ID assigned that's used to identify the widget to be mutated. Widget mutation
is only supported in Add-Ons.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `id` | `String` | The id of the widget, with a limit of 64 characters and in format of \`\[a-zA-Z0-9-\]+\`. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/widget` --- This object, for chaining.

*** ** * ** ***

### `setInputMode(inputMode)`

Sets whether this text input field supports variable insertion.

Only available for Google Workspace add-ons that extend Google Workspace Studio.

```javascript
const textInput = CardService.newTextInput()
                      .setFieldName('text_input_form_input_key')
                      .setTitle('Text input title')
                      .setInputMode(CardService.TextInputMode.PLAIN_TEXT);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `inputMode` | `https://developers.google.com/apps-script/reference/card-service/text-input-mode` | The type of input allowed for this text input field, use RICH_TEXT to support variable insertion. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setMultiline(multiline)`

Sets whether the input text shows on one line or multiple lines.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `multiline` | `Boolean` | The multiline setting. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setOnChangeAction(action)`

Sets an action to be performed whenever the text input changes.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The action to take. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setSuggestions(suggestions)`

Sets the suggestions for autocompletion in the text field.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `suggestions` | `https://developers.google.com/apps-script/reference/card-service/suggestions` | The collection of suggestions to use. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setSuggestionsAction(suggestionsAction)`

Sets the callback action to fetch suggestions based on user input for autocompletion. The
`https://developers.google.com/apps-script/reference/card-service/action` parameter must specify a callback function that returns a `https://developers.google.com/apps-script/reference/card-service/suggestions-response` object.

```javascript
const action = CardService.newAction()
                   .setFunctionName('suggestionCallback')
                   .setParameters({numSuggestions: 3});

CardService.newTextInput()
    .setFieldName('option-field')
    .setTitle('Option Selected')
    .setSuggestionsAction(action);

// ...

function suggestionCallback(e) {
  const suggestions = CardService.newSuggestions();
  const numSuggestions = Number.parseInt(e.parameter.numSuggestions);
  for (let i = 1; i <= numSuggestions; i++) {
    suggestions.addSuggestion(`Suggestion ${i}`);
  }
  return CardService.newSuggestionsResponseBuilder()
      .setSuggestions(suggestions)
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `suggestionsAction` | `https://developers.google.com/apps-script/reference/card-service/action` | The action that fetches suggestions for this input. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setTitle(title)`

Sets the title to be shown above the input field. Required.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The text label for this input. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setValidation(validation)`

Sets the validation rule for this widget.

```javascript
const validation = CardService.newValidation().setCharacterLimit('10').setType(
    CardService.InputType.TEXT);

const input = CardService.newTextInput()
                  .setFieldName('text_name_xxx1')
                  .setTitle('Max 10 characters')
                  .setValidation(validation);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `validation` | `https://developers.google.com/apps-script/reference/card-service/validation` | The validation rule for this `https://developers.google.com/apps-script/reference/card-service/text-input#` widget. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setValue(value)`

Sets the pre-filled value to be set in the input field.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The default value placed in the input. It is always represented as a string in the form callback parameters. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-input#` --- This object, for chaining.

*** ** * ** ***

### `setVisibility(visibility)`

Sets the visibility of the widget. The default value is \`VISIBLE\`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `visibility` | `https://developers.google.com/apps-script/reference/card-service/visibility` | The `https://developers.google.com/apps-script/reference/card-service/visibility` of the widget. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/widget` --- The Object, for chaining.