Class Action

Action

An action that enables interactivity within UI elements. The action does not happen directly on the client but rather invokes an Apps Script callback function with optional parameters.

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

const image = CardService.newImage().setOnClickAction(
    CardService.newAction().setFunctionName('handleImageClick').setParameters({
      imageSrc: 'carImage'
    }),
);

Methods

MethodReturn typeBrief description
addRequiredWidget(requiredWidget)ActionAdds the names of the widgets that this Action needs for a valid submission.
setAllWidgetsAreRequired(allWidgetsAreRequired)ActionIndicates whether this Action requires inputs from all widgets.
setFunctionName(functionName)ActionSets the name of the callback function to be called.
setInteraction(interaction)ActionSets the interaction with a user, only required when opening a dialog.
setLoadIndicator(loadIndicator)ActionSets the loading indicator that displays while the action is in progress.
setParameters(parameters)ActionAllows custom parameters to be passed to the callback function.
setPersistValues(persistValues)ActionIndicates whether form values are determined by the client's values or the server's values after an action response updates the form's Card.

Detailed documentation

addRequiredWidget(requiredWidget)

Adds the names of the widgets that this Action needs for a valid submission. If the widgets in this list don't have a value when this Action is invoked, the form submission is aborted.

Only available for Google Chat apps. Not available for Google Workspace Add-ons. 

const textInput = CardService.newTextInput()
                      .setFieldName('text_input_1')
                      .setTitle('Text input title');

// Creates a footer button that requires an input from the above TextInput
// Widget.
const action = CardService.newAction()
                   .setFunctionName('notificationCallback')
                   .addRequiredWidget('text_input_1');
const fixedFooter = CardService.newFixedFooter().setPrimaryButton(
    CardService.newTextButton().setText('help').setOnClickAction(action),
);

Parameters

NameTypeDescription
requiredWidgetStringThe name of the widget required by this Action.

Return

Action — This object, for chaining.

setAllWidgetsAreRequired(allWidgetsAreRequired)

Indicates whether this Action requires inputs from all widgets.

Only available for Google Chat apps. Not available for Google Workspace Add-ons. 

// Creates a button with an action that requires inputs from all widgets.
const button = CardService.newTextButton()
                   .setText('Create notification')
                   .setOnClickAction(
                       CardService.newAction().setAllWidgetsAreRequired(true));

Parameters

NameTypeDescription
allWidgetsAreRequiredBooleanWhether the action requires inputs from all widgets. Defaults to false.

Return

Action — This object, for chaining.

setFunctionName(functionName)

Sets the name of the callback function to be called. Required.

Parameters

NameTypeDescription
functionNameStringThe name of the function. You can use functions from included libraries, such as Library.libFunction1.

Return

Action — This object, for chaining.

setInteraction(interaction)

Sets the interaction with a user, only required when opening a dialog. If unspecified, the app responds by executing an Action like opening a link or running a function—as normal.

Only available for Google Chat apps. Not available for Google Workspace Add-ons. 

const action = CardService.newAction()
                   .setFunctionName('handleDialog')
                   .setInteraction(CardService.Interaction.OPEN_DIALOG);

Parameters

NameTypeDescription
interactionInteractionThe interaction to specify.

Return

Action — This object, for chaining.

setLoadIndicator(loadIndicator)

Sets the loading indicator that displays while the action is in progress.

Parameters

NameTypeDescription
loadIndicatorLoadIndicatorThe indicator to display.

Return

Action — This object, for chaining.

setParameters(parameters)

Allows custom parameters to be passed to the callback function. Optional.

Parameters

NameTypeDescription
parametersObjectBoth keys and values must be strings.

Return

Action — This object, for chaining.

setPersistValues(persistValues)

Indicates whether form values are determined by the client's values or the server's values after an action response updates the form's Card. When set to true, the client's values persist after the server response. When set to false, the server's values overwrite the form values. Defaults to false.

Persisting the client values helps prevent situations where a form changes unexpectedly after a user makes an edit. For example, if a user makes an edit to a TextInput after submitting a form, but before the server responds. If the values are persisted, the edit the user made remains after the server response updates the Card; otherwise the form value returns to the value that the user originally submitted to the form.

Persisting client values can interfere with your script's ability to clear form fields or override form values, so avoid turning on persistence for that type of functionality. Without persistence, it's recommended that you use the LoadIndicator.SPINNER for events, because this locks the UI and prevents user edits before the server responds. Alternatively, you can use LoadIndicator.NONE and make sure every element in the form has an onChange action. 

// Creates a button with an action that persists the client's values as the
// on-click action.
const button =
    CardService.newTextButton()
        .setText('Create notification')
        .setOnClickAction(
            CardService.newAction().setPersistValues(true).setFunctionName(
                'functionName'),
        );

Parameters

NameTypeDescription
persistValuesBooleanWhether to persist values. Defaults to false.

Return

Action — This object, for chaining.

Deprecated methods