Got 5 mins? Help us improve Add-ons documentation by taking a quick survey.

Package google.apps.card.v1

Index

Action

An action that describes the behavior when the form is submitted. For example, an Apps Script can be invoked to handle the form.

Fields
function

string

Apps Script function to invoke when the containing element is clicked/activated.

parameters[]

ActionParameter

List of action parameters.

loadIndicator

LoadIndicator

persistValues

bool

Indicates whether form values persist after the action. The default value is false.

If true, form values remain after the action is triggered. When using LoadIndicator.NONE for actions, persist_values = trueis recommended, as it ensures that any changes made by the user after form or on change actions are sent to the server are not overwritten by the response.

If false, the form values are cleared when the action is triggered. When persist_values is set to false, it is strongly recommended that the card use LoadIndicator.SPINNER for all actions, as this locks the UI to ensure no changes are made by the user while the action is being processed.

ActionParameter

List of string parameters to supply when the action method is invoked. For example, consider three snooze buttons: snooze now, snooze 1 day, snooze next week. You might use action method = snooze(), passing the snooze type and snooze time in the list of string parameters.

Fields
key

string

The name of the parameter for the action script.

value

string

The value of the parameter.

LoadIndicator

Specifies the loading indicator that the action displays while making the call to the action.

Enums
SPINNER Displays a spinner to indicate that content is loading.
NONE Nothing is displayed.

BorderStyle

Represents the complete border style applied to widgets.

Fields
type

BorderType

The border type.

strokeColor

Color

The colors to use when the type is BORDER_TYPE_STROKE.

cornerRadius

int32

The corner radius for the border.

BorderType

Represents the border types applied to widgets.

Enums
BORDER_TYPE_UNSPECIFIED No value specified.
NO_BORDER No border.
STROKE Outline.

Button

A button. Can be a text button or an image button.

Fields
text

string

The text of the button.

icon

Icon

The icon image.

color

Color

If set, the button is filled with a solid background.

onClick

OnClick

The action to perform when the button is clicked.

disabled

bool

If true, the button is displayed in a disabled state and doesn't respond to user actions.

altText

string

The alternative text used for accessibility. Has no effect when an icon is set; use icon.alt_text instead.

ButtonList

A list of buttons layed out horizontally.

Fields
buttons[]

Button

Card

A card is a UI element that can contain UI widgets such as text and images. For more information, see Cards . For example, the following JSON creates a card that has a header with the name, position, icons, and link for a contact, followed by a section with contact information like email and phone number.

{
  "header": {
    "title": "Heba Salam",
    "subtitle": "Software Engineer",
    "imageStyle": "ImageStyle.AVATAR",
    "imageUrl": "https://example.com/heba_salam.png",
    "imageAltText": "Avatar for Heba Salam"
  },
  "sections" : [
    {
      "header": "Contact Info",
      "widgets": [
        {
          "decoratedText": {
            "icon": {
              "knownIcon": "EMAIL"
            },
            "content": "heba.salam@example.com"
          }
        },
        {
          "decoratedText": {
            "icon": {
              "knownIcon": "PERSON"
            },
            "content": "<font color=\"#80e27e\">Online</font>"
          }
        },
        {
          "decoratedText": {
            "icon": {
              "knownIcon": "PHONE"
            },
            "content": "+1 (555) 555-1234"
          }
        },
        {
          "buttons": [
            {
              "textButton": {
                "text": "Share",
              },
              "onClick": {
                "openLink": {
                  "url": "https://example.com/share"
                }
              }
            },
            {
              "textButton": {
                "text": "Edit",
              },
              "onClick": {
                "action": {
                  "function": "goToView",
                  "parameters": [
                    {
                      "key": "viewType",
                      "value": "EDIT"
                    }
                  ],
                  "loadIndicator": "LoadIndicator.SPINNER"
                }
              }
            }
          ]
        }
      ],
      "collapsible": true,
      "uncollapsibleWidgetsCount": 3
    }
  ],
  "cardActions": [
    {
      "actionLabel": "Send Feedback",
      "onClick": {
        "openLink": {
          "url": "https://example.com/feedback"
        }
      }
    }
  ],
  "name": "contact-card-K3wB6arF2H9L"
}
Fields
header

CardHeader

The header of the card. A header usually contains a title and an image.

sections[]

Section

Sections are separated by a line divider.

cardActions[]

CardAction

The actions of this card. They are added to a card's generated toolbar menu. For example, the following JSON constructs a card action menu with Settings and Send Feedback options:

"cardActions": [
  {
    "actionLabel": "Setting",
    "onClick": {
      "action": {
        "functionName": "goToView",
        "parameters": [
          {
            "key": "viewType",
            "value": "SETTING"
         }
        ],
        "loadIndicator": "LoadIndicator.SPINNER"
      }
    }
  },
  {
    "actionLabel": "Send Feedback",
    "onClick": {
      "openLink": {
        "url": "https://example.com/feedback"
      }
    }
  }
]
name

string

Name of the card, which is used as a identifier for the card in card navigation.

fixedFooter

CardFixedFooter

The fixed footer shown at the bottom of this card.

displayStyle

DisplayStyle

The display style for peekCardHeader.

peekCardHeader

CardHeader

When displaying contextual content, the peek card header acts as a placeholder so that the user can navigate forward between the homepage cards and the contextual cards.

CardAction

A card action is the action associated with the card. For example, an invoice card might include actions such as delete invoice, email invoice, or open the invoice in a browser.

Fields
actionLabel

string

The label that displays as the action menu item.

onClick

OnClick

The onclick action for this action item.

CardFixedFooter

A persistent (sticky) footer that is added to the bottom of the card.

Fields
primaryButton

Button

The primary button of the fixed footer. The button must be a text button with text and color set.

secondaryButton

Button

The secondary button of the fixed footer. The button must be a text button with text and color set. primaryButton must be set if secondaryButton is set.

CardHeader

Fields
title

string

The title of the card header. The title must be specified. The header has a fixed height: if both a title and subtitle are specified, each takes up one line. If only the title is specified, it takes up both lines.

subtitle

string

The subtitle of the card header.

imageType

ImageType

The image's type.

imageUrl

string

The URL of the image in the card header.

imageAltText

string

The alternative text of this image which is used for accessibility.

DisplayStyle

Determines how a card is displayed.The default DisplayStyle is REPLACE.

Enums
DISPLAY_STYLE_UNSPECIFIED
PEEK The header of the card appears at the bottom of the sidebar, partially covering the current top card of the stack. Clicking the header pops the card into the card stack. If the card has no header, a generated header is used instead.
REPLACE The card is shown by replacing the view of the top card in the card stack.

Section

A section contains a collection of widgets that are rendered vertically in the order that they are specified. Across all platforms, cards have a narrow fixed width, so there is currently no need for layout properties, for example, float.

Fields
header

string

The header of the section. Formatted text is supported.

widgets[]

Widget

A section must contain at least 1 widget.

collapsible

bool

Indicates whether this section is collapsible. If a section is collapsible, the description must be given.

uncollapsibleWidgetsCount

int32

The number of uncollapsible widgets. For example, when a section contains five widgets and the numUncollapsibleWidget is set to 2, the first two widgets are always shown and the last three are collapsed as default. The numUncollapsibleWidget is taken into account only when collapsible is set to true.

DateTimePicker

The widget that lets users to specify a date and time.

Fields
name

string

The name of the text input that's used in formInput, and uniquely identifies this input.

label

string

The label for the field that displays to the user.

type

DateTimePickerType

The type of the date/time picker.

valueMsEpoch

int64

The value to display as the default value before user input or previous user input. It is represented in milliseconds (Epoch time). For DATE_AND_TIME type, the full epoch value is used. For DATE_ONLY type, only date of the epoch time is used. For TIME_ONLY type, only time of the epoch time is used. For example, you can set epoch time to 3 * 60 * 60 * 1000 to represent 3am.

timezoneOffsetDate

int32

The number representing the time zone offset from UTC, in minutes. If set, the value_ms_epoch is displayed in the specified time zone. If not set, it uses the user's time zone setting on the client side.

onChangeAction

Action

Triggered when the user clicks Save or Clear from the date/time picker dialog. This is only triggered if the value changed as a result of the Save/Clear operation.

DateTimePickerType

The type of the date/time picker.

Enums
DATE_AND_TIME The user can select a date and time.
DATE_ONLY The user can only select a date.
TIME_ONLY The user can only select a time.

DecoratedText

A widget that displays text with optional decorations such as a label above or below the text, an icon in front of the text, a selection widget or a button after the text.

Fields
icon
(deprecated)

Icon

Deprecated in favor of startIcon.

startIcon

Icon

The icon displayed in front of the text.

topLabel

string

The formatted text label that shows above the main text.

text

string

Required. The main widget formatted text. See Text formatting for details.

wrapText

bool

The wrap text setting. If true, the text is wrapped and displayed in multiline. Otherwise, the text is truncated.

bottomLabel

string

The formatted text label that shows below the main text.

onClick

OnClick

Only the top and bottom label and content region are clickable.

Union field control. A control widget or image that appears after the text. You can set a button, switch control, or image, but not more than one. control can be only one of the following:
button

Button

A button that can be clicked to trigger an action.

switchControl

SwitchControl

A switch widget can be clicked to change its state or trigger an action.

endIcon

Icon

An icon displayed after the text.

SwitchControl

Fields
name

string

The name of the switch widget that's used in formInput.

value

string

The value is what is passed back in the callback.

selected

bool

If the switch is selected.

onChangeAction

Action

The action when the switch state is changed.

controlType

ControlType

The control type, either switch or checkbox.

ControlType

The switch type shown in client.

Enums
SWITCH
CHECKBOX Deprecated in favor of CHECK_BOX.
CHECK_BOX

Divider

A divider that appears in between widgets.

GetAutocompletionResponse

A response to getting autocomplete container, which includes elements necessary for showing auto complete items for text field. For example:

{
  "autoComplete": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
Fields
autoComplete

Suggestions

schema

string

This is a no-op schema field that might be present in the markup for syntax checking.

Grid

Represents a Grid widget that displays items in a configurable grid layout.

Fields
title

string

The text that displays in the grid header.

items[]

GridItem

The items to display in the grid.

borderStyle

BorderStyle

The border style to apply to each grid item.

columnCount

int32

The number of columns to display in the grid. A default value is used if this field isn't specified, and that default value is different depending on where the grid is shown (dialog versus companion).

onClick

OnClick

This callback is reused by each individual grid item, but with the item's identifier and index in the items list added to the callback's parameters.

GridItem

Represents a single item in the grid layout.

Fields
id

string

A user-specified identifier for this grid item. This identifier is returned in the parent Grid's onClick callback parameters.

image

ImageComponent

The image that displays in the grid item.

title

string

The grid item's title.

subtitle

string

The grid item's subtitle.

textAlignment

HorizontalAlignment

The horizontal alignment of the grid item's text.

layout

GridItemLayout

The layout to use for the grid item.

GridItemLayout

Represents the various layout options available for a grid item.

Enums
GRID_ITEM_LAYOUT_UNSPECIFIED No layout specified.
TEXT_BELOW The title and subtitle are shown below the grid item's image.
TEXT_ABOVE The title and subtitle are shown above the grid item's image.

Icon

Fields
altText

string

The description of the icon, used for accessibility. The default value is provided if you don't specify one.

imageType

ImageType

The crop style applied to the image. In some cases, applying a CIRCLE crop causes the image to be drawn larger than a standard icon.

Union field icons. The icon, can be specified by KnownIcon string or a URL. icons can be only one of the following:
knownIcon

string

The icon specified by the string name of a list of known icons

iconUrl

string

The icon specified by a URL.

Image

An image that is specified by a URL and can have an onClick action.

Fields
imageUrl

string

An image URL.

onClick

OnClick

altText

string

The alternative text of this image, used for accessibility.

ImageComponent

Fields
imageUri

string

The image URL.

altText

string

The accessibility label for the image.

cropStyle

ImageCropStyle

The crop style to apply to the image.

borderStyle

BorderStyle

The border style to apply to the image.

ImageCropStyle

Represents the crop style applied to an image.

Fields
type

ImageCropType

The crop type.

aspectRatio

double

The aspect ratio to use if the crop type is RECTANGLE_CUSTOM.

ImageCropType

Represents the crop style applied to an image.

Enums
IMAGE_CROP_TYPE_UNSPECIFIED No value specified.
SQUARE Applies a square crop.
CIRCLE Applies a circular crop.
RECTANGLE_CUSTOM Applies a rectangular crop with a custom aspect ratio.
RECTANGLE_4_3 Applies a rectangular crop with a 4:3 aspect ratio.

Card action that manipulates the card stack. For example:

1) Add a new card to the stack (navigate forward).

 navigations : {
    pushCard : CARD
  }

2) Update the card on top of the stack (in place update).

  navigations : {
    popCard : true,
  }, {
    pushCard : CARD
  }

3) Go back one step without updating.

  navigations : {
    popCard : true,
  }

4) Go back multiple steps and update that card.

  navigations : {
    popCard : true,
  }, ... {
    pushCard : CARD
  }

5) Go back multiple steps to a defined CARD_NAME.

  navigations : {
    popToCardName : CARD_NAME,
  }, {
    pushCard : CARD
  }

6) Go back to the root and update that card.

  navigations : {
    popToRoot : true
  }, {
    pushCard : CARD
  }

7) Pop to the specified card and pop that one as well.

navigations : { popToCardName : CARD_NAME }, { popCard : true, }

8) Replace the top card with a new card.

  navigations : {
    updateCard : CARD
  }
Fields

Union field navigate_action.

navigate_action can be only one of the following:

popToRoot

bool

Card stack pops all cards off except the root card.

pop

bool

Card stack pops one card off.

popToCard

string

Card stack pops all cards above the specified card with given card name.

pushCard

Card

Card stack pushes a card onto the card stack.

updateCard

Card

Card stack updates the top card with a new card and preserves filled form fields values. For a non-equivalent field, the value is dropped.

Notification

Card action that displays a notification in the host app.

Fields
text

string

Plain text to display for the notification, without HTML tags.

OnClick

Fields

Union field data.

data can be only one of the following:

action

Action

If specified, an action is triggered by this onClick.

openDynamicLinkAction

Action

An add-on triggers this action when the action needs to open a link. This differs from the openLink above in that this needs to talk to server to get the link. Thus some preparation work is required for web client to do before the open link action response comes back.

card

Card

A new card is pushed to the card stack after clicking if specified.

OnClose

When an OnClick opens a link, then the client either forgets about it or observes until the window is closed. The implementation depends on the client platform capabilities.

OnClose might cause OpenAs to be ignored; if the client platform can't support both selected values together, OnClose takes precedence.

Enums
NOTHING

Doesn’t reload the card after the child window closes. Reloads the card after the child window closes.

If used in conjunction with OpenAs.OVERLAY, the child window acts as a modal dialog and the main card is blocked until the child window closes.

RELOAD

OpenAs

When an OnClick opens a link, then the client can either open it as a full size window (if that is the frame used by the client), or an overlay (such as a pop-up). The implementation depends on the client platform capabilities, and the value selected might be ignored if the client doesn't support it. FULL_SIZE is supported by all clients.

Enums
FULL_SIZE The link opens as a full size window (if that's the frame used by the client.
OVERLAY The link opens as an overlay, such as a pop-up.

RenderActions

A set of render instructions that tells a card to perform an action and/or tells the add-on host app to perform an app-specific action.

Fields
action

Action

hostAppAction

HostAppActionMarkup

Actions handled by individual host apps.

schema

string

This is a no-op schema field that might be present in the markup for syntax checking.

Action

Fields
navigations[]

Navigation

Push, pop, or update displayed cards.

notification

Notification

Display a notification to the end-user.

SelectionInput

A widget that creates a UI item (for example, a drop-down list) with options for users to select.

Fields
name

string

The name of the text input which is used in formInput.

label

string

The label displayed ahead of the switch control.

type

SelectionType

items[]

SelectionItem

onChangeAction

Action

If specified, the form is submitted when the selection changes. If not specified, you must specify a separate button.

SelectionItem

The item in the switch control. A radio button, at most one of the items is selected.

Fields
text

string

The text to be displayed.

value

string

The value associated with this item. The client should use this as a form input value.

selected

bool

If more than one item is selected for RADIO_BUTTON and DROPDOWN, the first selected item is treated as selected and the ones after are ignored.

SelectionType

The type of the selection.

Enums
CHECK_BOX The selection type is a checkbox.
RADIO_BUTTON The selection type is a radio button.
SWITCH The selection type is a switch.
DROPDOWN The selection type is a dropdown.

SubmitFormResponse

A response to a form submit other than getting an autocomplete container, which contains the actions the card should perform and/or the add-on host app should perform, and whether the card's state has changed. For example:

{
  "renderActions": {
    "action": {
      "notification": {
        "text": "Email address is added: salam.heba@example.com"
      }
    },
    "hostAppAction": {
      "gmailAction": {
        "openCreatedDraftAction": {
          "draftId": "msg-a:r-79766936926021702",
          "threadServerPermId": "thread-f:15700999851086004"
        }
      }
    }
  }
}
Fields
renderActions

RenderActions

A set of render instructions that tells the card to perform an action and/or tells the add-on host app to perform an app-specific action.

stateChanged

bool

Whether the state of the cards has changed and data in existing cards is stale.

schema

string

This is a no-op schema field that may be present in the markup for syntax checking.

Suggestions

A container wrapping elements necessary for showing suggestion items used in text input autocomplete.

Fields
items[]

SuggestionItem

A list of suggestions items which will be used in are used in autocomplete.

SuggestionItem

A suggestion item. Only supports text for now.

Fields
text

string

TextInput

A text input is a UI item where users can input text. A text input can also have an onChange action and suggestions.

Fields
name

string

The name of the text input which is used in formInput.

label

string

At least one of label and hintText must be specified.

hintText

string

The hint text.

value

string

The default value when there is no input from the user.

type

Type

The style of the text, for example, a single line or multiple lines.

onChangeAction

Action

The onChange action, for example, invoke a function.

initialSuggestions

Suggestions

The initial suggestions made before any user input.

autoCompleteAction

Action

The refresh function that returns suggestions based on the user's input text. If the callback is not specified, autocomplete is done in client side based on the initial suggestion items.

multipleSuggestions

bool

When set to true, a user can input multiple suggestion items.

Type

The style of the text, for example, a single line or multiple lines.

Enums
SINGLE_LINE The text is put into a single line.
MULTIPLE_LINE The text is put into multiple lines.

TextParagraph

A paragraph of text that supports formatting. See Text formatting for details.

Fields
text

string

The text that's shown in the widget.

Widget

A widget is a UI element that presents texts, images, etc.

Fields
horizontalAlignment

HorizontalAlignment

The horizontal alignment of this widget.

Union field data. A widget can only have one of the following items. You can use multiple widget fields to display more items. data can be only one of the following:
textParagraph

TextParagraph

Displays a text paragraph in this widget. For example, the following JSON creates a bolded text:

"textParagraph": {
  "text": "  <b>bold text</b>"
}
image

Image

Displays an image in this widget. For example, the following JSON creates an image with alternative text:

"image": {
  "imageUrl": "https://example.com/heba_salam.png"
  "altText": "Avatar for Heba Salam"
}
decoratedText

DecoratedText

Displays a decorated text item in this widget. For example, the following JSON creates a decorated text widget showing email address:

"decoratedText": {
  "icon": {
    "knownIcon": "EMAIL"
  },
  "topLabel": "Email Address",
  "content": "heba.salam@example.com",
  "bottomLabel": "This is a new Email address!",
  "switchWidget": {
    "name": "has_send_welcome_email_to_heba_salam",
    "selected": false,
    "controlType": "ControlType.CHECKBOX"
  }
}
buttonList

ButtonList

A list of buttons. For example, the following JSON creates two buttons. The first is a filled text button and the second is an image button that opens a link:

"buttonList": {
  "buttons": [
    "button": {
      "text": "Edit",
      "Color": {
        "Red": 255
        "Green": 255
        "Blue": 255
       }
      "disabled": true
    },
    "button": {
      "icon": {
        "knownIcon": "INVITE"
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    },
  ]
}
textInput

TextInput

Displays a text input in this widget. For example, the following JSON creates a text input for mail address:

"textInput": {
  "name": "mailing_address",
  "label": "Mailing Address"
}

As another example, the following JSON creates a text input for programming language with static suggestions:

"textInput": {
  "name": "preferred_programing_language",
  "label": "Preferred Language",
  "initialSuggestions": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
selectionInput

SelectionInput

Displays a switch control in this widget. For example, the following JSON creates a dropdown selection for size:

"switchControl": {
  "name": "size",
  "label": "Size"
  "type": "SelectionType.DROPDOWN",
  "items": [
    {
      "text": "S",
      "value": "small",
      "selected": false
    },
    {
      "text": "M",
      "value": "medium",
      "selected": true
    },
    {
      "text": "L",
      "value": "large",
      "selected": false
    },
    {
      "text": "XL",
      "value": "extra_large",
      "selected": false
    }
  ]
}
dateTimePicker

DateTimePicker

Displays a selection/input widget for date/time. For example, the following JSON creates a date/time picker for an appointment time:

"dateTimePicker": {
  "name": "appointment_time",
  "label": "Book your appointment at:",
  "type": "DateTimePickerType.DATE_AND_TIME",
  "valueMsEpoch": "796435200000"
}
divider

Divider

Displays a divider. For example, the following JSON creates a divider:

"divider": {
}
grid

Grid

Displays a grid with a collection of items. For example, the following JSON creates a 2 column grid with a single item:

"grid": {
  "title": "A fine collection of items",
  "numColumns": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4.0
  },
  "items": [
    "image": {
      "imageUri": "https://www.example.com/image.png",
      "cropStyle": {
        "type": "SQUARE"
      },
      "borderStyle": {
        "type": "STROKE"
      }
    },
    "title": "An item",
    "textAlignment": "CENTER"
  ],
  "onClick": {
    "openLink": {
      "url":"https://www.example.com"
    }
  }
}

HorizontalAlignment

The horizontal alignment determines the placement of the widget. By default, a widget is shown using alignment corresponding to the START value, where START corresponds to the left in left-to-right layouts, and the right in right-to-left layouts. The END value corresponds to the right in left-to-right layouts, and the left in right-to-left layouts.

Enums
HORIZONTAL_ALIGNMENT_UNSPECIFIED Unspecified alignment.
START Alignment to the start position.
CENTER Alignment to the center position.
END Alignment to the end position.

ImageType

The image type determines the cropping of the image that it is applied to. SQUARE means that no cropping is applied, CIRCLE applies a circular mask to the image.

Enums
SQUARE Applies no cropping to the image.
CIRCLE Applies a circular mask to the image.