Page Summary

outlined_flag

• Add-on actions provide interactive behavior to widgets by defining what happens when a user interacts with them, such as selecting or updating a widget.

• You define actions usingAction objects, which are associated with callback functions that execute when the action is triggered.

• Widget handler functions link widgets to specific actions and determine the type of user interaction that triggers the action's callback function.

• Callback functions can perform various tasks and may need to return specific response objects, likeActionResponse for navigation orSuggestionResponse for autocomplete suggestions.

• Action event objects, containing client-side context information, are automatically passed to callback functions when an action is triggered.

Add-on actions provide interactive behavior towidgets.By creating an action, you define what happens when the user selects or updatesa widget.

In most cases you can define add-on actions usingActionobjects provided by the Apps ScriptCard service.EachAction is associated withacallback function when you create it. You implement the callback functionto take selected steps when the user interacts with the widget. You must alsolink theAction to the widgetusing an appropriatewidget handler function thatdefines what kind of interaction triggers theAction callback.

Configure a widget with anActionusing this general process:

1. Create theAction object,specifying the callback function that it shouldexecute along with any parameters it requires.
2. Call the appropriatewidget handler functionon the widget using theActionobject.
3. Implement the callback function to enact the required behavior.

Note: Don't confuseActionobjects withCardActionobjects.CardAction objectsare card header menu items, whileActionobjects define responses to user interactions with the UI.

Widget handler functions

To link a widget to a specificActionor other behavior, you use a widgethandler function. The handler function determines what kind of interaction(for example, clicking the widget or editing a text field) triggers theaction behavior. The handler function also defines what steps the UI takes,if any, after the action completes.

The following table lists the different handler types for widgets and whatwidgets they are used with:

Handler function	Triggers action	Applicable widgets	Description
setOnChangeAction()	The widget value changes	DatePicker DateTimePicker SelectionInput Switch TextInputTimePicker	Sets anAction that executes an Apps Script function when the widget loses focus, such as such as when the user enters text in an input and presses Enter. The handler automatically passes anevent object to the function it calls. You can insert additional parameter information in this event object if selected.
setOnClickAction()	The user clicks the widget	CardAction Image ImageButton DecoratedText TextButton	Sets anAction that executes an Apps Script function when the user clicks the widget. The handler automatically passes anevent object to the function it calls. You can insert optional parameter information in this event object.
setComposeAction()	The user clicks the widget	CardAction Image ImageButton DecoratedText TextButton	Gmail specific. Sets anAction that builds an email draft, then presents that draft to the user in a Gmail UI compose window. You can build the draft as a new message or a reply to the open message in Gmail. When the handler calls the draft-building callback function, it passes anevent object to the callback function. SeeCompose draft messages for more details.
setOnClickOpenLinkAction()	The user clicks the widget	CardAction Image ImageButton DecoratedText TextButton	Sets anAction to open a URL when the user clicks the widget. Use this handler when you must construct the URL or other actions must take place before the link opens; otherwise it is usually simpler to usesetOpenLink(). You can only open the URL in a new window. When closed, you can cause the UI to reload the add-on.
setOpenLink()	The user clicks the widget	CardAction Image ImageButton DecoratedText TextButton	Directly opens a URL when the user clicks the widget. Use this handler when you know the URL and only need to open it; otherwise usesetOnClickOpenLinkAction(). You can open the URL in a new window or in an overlay. When closed, you can cause the UI to reload the add-on.
setSuggestionsAction()	The user enters text into an input	TextInput	Sets anAction that executes an Apps Script function when the user enters text into a text input widget. The handler automatically passes anevent object to the function it calls. SeeAutocomplete suggestions for text inputs for more details.

Callback functions

Callback functions execute when anActiontriggers. Because callback function are Apps Script functions, you can have themdo almost anything any other script function can do.

Warning: The Apps ScriptCard servicelimits callback functions to a maximum of 30 seconds of execution time. Ifthe execution takes longer than that, your add-on UI may not update itscard display properly in response to theAction.

A callback function sometimes returns a specific response object. Thesetypes of responses indicate additional operations that need to happen afterthe callback finishes executing, such as displaying a new card or presentingautocomplete suggestions. When your callback function must return a specificresponse object, you use a builder class in theCard serviceto construct that object.

The following table shows when your callback functions must return aspecific response object for specific actions. These actions are allindependent of the specific host application the add-on is extending:

Action attempted	Callback function should return
Navigate between cards	ActionResponse
Display aNotification	ActionResponse
Open a link usingsetOnClickOpenLinkAction()	ActionResponse
Display autocomplete suggestions	SuggestionResponse
Use auniversal action	UniversalActionResponse
Other actions	Nothing

Actions for Google Workspace host applications

In addition to these actions, each host application has its own set ofactions that can only be taken in that host. For details, see the followingguides:

• Calendar actions
• Chat actions
• Drive actions
• Gmail actions
• Editor actions

Note: When using the response builder classes, make sure to callbuild() toproduce the response objects. Failing to do so results in an error.Note:Universal actions are definedin the project manifest and don't needActionobjects, but their callback functions must return aUniversalActionResponse.

Action event objects

When your add-on triggers anAction,the UI automatically constructs a JSONevent object and passes it as anargument to theAction callbackfunction. This event object contains information about the user's currentclient-side context, such as the current values of all the interactivewidgets in the displayed card.

Action event objects have a specific JSON structure that organizes theinformation that they contain. The same structure is used when ahomepage triggerfires to create a homepage, or when acontextual triggerfires to update the add-on display.

SeeEvent objects for a fullexplanation of the event object structure.

Note: Gmail add-ons used a simplified version of this event object structure,which is now deprecated. For backward compatibility all of the originalGmail add-ons event object fields are still contained within the new eventobject structure (seeevent object structure).However, the same information is reproduced in thecommon eventandGmail eventobject substructures. If you are upgrading a Gmail add-on into aGoogle Workspace add-on, you should adjust your codeto use the updated event object fields — eventually the original Gmailevent object fields will be removed.