DecoratedText

A widget that displays text with optional decorations. Possible keys include an icon, a label
above and a label below. Setting the text content and one of the keys is required using `https://developers.google.com/apps-script/reference/card-service/decorated-text#setText(String)` and one of `https://developers.google.com/apps-script/reference/card-service/decorated-text#`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setTopLabel(String)`, or `https://developers.google.com/apps-script/reference/card-service/decorated-text#setBottomLabel(String)`. This class is intended to replace `https://developers.google.com/apps-script/reference/card-service/key-value`.

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

```javascript
const decoratedText =
    CardService.newDecoratedText().setText('Text').setTopLabel('TopLabel');

const multilineDecoratedText = CardService.newDecoratedText()
                                   .setText('Text')
                                   .setTopLabel('TopLabel')
                                   .setWrapText(true)
                                   .setBottomLabel('BottomLabel');
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#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/decorated-text#setAuthorizationAction(AuthorizationAction)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets an authorization action that opens a URL to the authorization flow when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setBottomLabel(String)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the label text to be used as the key and is displayed below the text content. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setButton(Button)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the `https://developers.google.com/apps-script/reference/card-service/button` that is displayed to the right of the text. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets an action that composes a draft email when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setEndIcon(IconImage)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the optional `https://developers.google.com/apps-script/reference/card-service/icon-image` that is displayed to the right of the content. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#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/decorated-text#setOnClickAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets an action that executes when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets an action that opens a URL in a tab when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets a URL to be opened when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setStartIcon(IconImage)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the optional `https://developers.google.com/apps-script/reference/card-service/icon-image` to display before the text content. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setSwitchControl(Switch)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the `https://developers.google.com/apps-script/reference/card-service/switch` that is displayed to the right of the content. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setText(String)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the text to be used as the value. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setTopLabel(String)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets the label text to be used as the key and is displayed above the text content. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setVisibility(Visibility)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Sets the visibility of the widget. |
| `https://developers.google.com/apps-script/reference/card-service/decorated-text#setWrapText(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/decorated-text#` | Sets whether the value text should be displayed on a single line or multiple lines. |

## 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.

*** ** * ** ***

### `setAuthorizationAction(action)`

Sets an authorization action that opens a URL to the authorization flow when the object is
clicked. This opens the URL in a new window. When the user finishes the authorization flow and
returns to the application, the add-on reloads.

A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` set.

```javascript
// ...

const action = CardService.newAuthorizationAction().setAuthorizationUrl('url');
CardService.newTextButton().setText('Authorize').setAuthorizationAction(action);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/authorization-action` | The object that specifies the authorization action to take when this element is clicked. |

#### Return


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

*** ** * ** ***

### `setBottomLabel(text)`

Sets the label text to be used as the key and is displayed below the text content.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | The label text. |

#### Return


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

*** ** * ** ***

### `setButton(button)`

Sets the `https://developers.google.com/apps-script/reference/card-service/button` that is displayed to the right of the text. A `https://developers.google.com/apps-script/reference/card-service/decorated-text#` can
only support one button or one switch.

#### Parameters

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

#### Return


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

*** ** * ** ***

### `setComposeAction(action, composedEmailType)`

Sets an action that composes a draft email when the object is clicked. A UI object can only
have one of `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)`,
`https://developers.google.com/apps-script/reference/card-service/decorated-text#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` set.

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/compose-action-response` object configured using `https://developers.google.com/apps-script/reference/card-service/compose-action-response-builder#setGmailDraft(GmailDraft)`.


> [!NOTE]
> **Note** : This method doesn't set a **compose action** that is used to [extend the compose UI](https://developers.google.com/gmail/add-ons/how-tos/extending-compose-ui). Rather, this method connects this UI element to an `https://developers.google.com/apps-script/reference/card-service/action` that [composes draft messages](https://developers.google.com/gmail/add-ons/how-tos/compose) in Apps Script that are opened in Gmail when the action completes.

<br />

```javascript
// ...

const action = CardService.newAction().setFunctionName('composeEmailCallback');
CardService.newTextButton()
    .setText('Compose Email')
    .setComposeAction(action, CardService.ComposedEmailType.REPLY_AS_DRAFT);

// ...

function composeEmailCallback(e) {
  const thread = GmailApp.getThreadById(e.threadId);
  const draft = thread.createDraftReply('This is a reply');
  return CardService.newComposeActionResponseBuilder()
      .setGmailDraft(draft)
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The object that specifies the compose action to take when this element is clicked. |
| `composedEmailType` | `https://developers.google.com/apps-script/reference/card-service/composed-email-type` | An enum value that specifies whether the composed draft is a standalone or reply draft. |

#### Return


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

*** ** * ** ***

### `setEndIcon(endIcon)`

Sets the optional `https://developers.google.com/apps-script/reference/card-service/icon-image` that is displayed to the right of the content. A `https://developers.google.com/apps-script/reference/card-service/decorated-text#` can only support one button, one switch or one icon.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `endIcon` | `https://developers.google.com/apps-script/reference/card-service/icon-image` | The icon to add. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/decorated-text#` --- 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.

*** ** * ** ***

### `setOnClickAction(action)`

Sets an action that executes when the object is clicked. A UI object can only have one of
`https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` set.

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/action-response` object.

```javascript
// ...

const action = CardService.newAction().setFunctionName('notificationCallback');
CardService.newTextButton()
    .setText('Create notification')
    .setOnClickAction(action);

// ...

function notificationCallback() {
  return CardService.newActionResponseBuilder()
      .setNotification(
          CardService.newNotification().setText('Some info to display to user'),
          )
      .build();
}
```

#### Parameters

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

#### Return


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

*** ** * ** ***

### `setOnClickOpenLinkAction(action)`

Sets an action that opens a URL in a tab when the object is clicked. Use this function when the
URL needs to be built or when you need to take other actions in addition to creating the `https://developers.google.com/apps-script/reference/card-service/open-link` object. A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setAuthorizationAction(AuthorizationAction)`, or
`https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` set.

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/action-response` object configured using `https://developers.google.com/apps-script/reference/card-service/action-response-builder#setOpenLink(OpenLink)`.

```javascript
// ...

const action = CardService.newAction().setFunctionName('openLinkCallback');
CardService.newTextButton()
    .setText('Open Link')
    .setOnClickOpenLinkAction(action);

// ...

function openLinkCallback() {
  return CardService.newActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink().setUrl('https://www.google.com'))
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The object that specifies the open link action to take when this element is clicked. |

#### Return


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

*** ** * ** ***

### `setOpenLink(openLink)`

Sets a URL to be opened when the object is clicked. Use this function when the URL is already
known and only needs to be opened. A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOpenLink(OpenLink)`,
`https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/decorated-text#setAuthorizationAction(AuthorizationAction)`,
or `https://developers.google.com/apps-script/reference/card-service/decorated-text#setComposeAction(Action,ComposedEmailType)` set.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `openLink` | `https://developers.google.com/apps-script/reference/card-service/open-link` | An `https://developers.google.com/apps-script/reference/card-service/open-link` object describing the URL to open. |

#### Return


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

*** ** * ** ***

### `setStartIcon(startIcon)`

Sets the optional `https://developers.google.com/apps-script/reference/card-service/icon-image` to display before the text content.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `startIcon` | `https://developers.google.com/apps-script/reference/card-service/icon-image` | The icon to display. |

#### Return


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

*** ** * ** ***

### `setSwitchControl(switchToSet)`

Sets the `https://developers.google.com/apps-script/reference/card-service/switch` that is displayed to the right of the content. A `https://developers.google.com/apps-script/reference/card-service/decorated-text#`
can only support one button or one switch.

#### Parameters

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

#### Return


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

*** ** * ** ***

### `setText(text)`

Sets the text to be used as the value. Supports [basic HTML formatting](https://developers.google.com/gmail/add-ons/concepts/widgets#text_formatting). Required.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | The text content for this widget. |

#### Return


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

*** ** * ** ***

### `setTopLabel(text)`

Sets the label text to be used as the key and is displayed above the text content.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | The label text. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/decorated-text#` --- 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.

*** ** * ** ***

### `setWrapText(wrapText)`

Sets whether the value text should be displayed on a single line or multiple lines.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `wrapText` | `Boolean` | If `true`, the text is wrapped and displayed on multiple lines. Otherwise the text is truncated. |

#### Return


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