Dialogs and sidebars for editor add-ons

For most editor add-ons, dialog windows and sidebar panels are the primary add-on user interfaces. Both are fully customizable using standard HTML and CSS, and you can use Apps Script's client-server communication model to run Apps Script functions when the user interacts with the sidebar or dialog. Your add-on can define multiple sidebars and dialogs, but the add-on can display only one at a time.

When you want to prevent the user from interacting with the editor until they make some choice in the add-on interaface, use a dialog; otherwise use a sidebar.

Dialogs

Dialogs are window panels that overlay the primary editor content. Apps Script dialogs are modal; while they are opened the user can't interact with the other elements of the editor interface. You can customize the content and size of dialogs.

You build add-on dialogs the same way as Apps Script custom dialogs; the general recommended procedure is the following:

  1. Create a script project file that defines your dialog's HTML structure, CSS, and client-side JavaScript behavior. When defining the dialog, refer to the editor add-on style guidlines.
  2. In your server-side code where you want the dialog to open, call HtmlService.createHtmlOutputFromFile(filename) to create an HtmlOutput object representing the dialog. Alternatively, if you are using templated HTML you can call HtmlService.createTemplateFromFile(filename) to generate a template and then HtmlTemplate.evaluate() to convert it to an HtmlOutput object.
  3. Call Ui.showModalDialog(htmlOutput, dialogTitle) to display the dialog using that HtmlOutput.

Dialogs don't suspend the server-side script while they are open. The client-side JavaScript can make asynchronous calls to the server-side using google.script.run() and associated handler functions. For more details, see Client-to-server communication.

File-open dialogs

File-open dialogs are pre-built dialogs that let your users select files from their Google Drive. You can add a file-open dialog to your add-on without needing to design it, but it requires some additional configuration. You also require access to the add-on's Cloud Platform project in order to enable the Google Picker API.

For full details, see File-open dialogs.

Sidebars are panels that appear in the right of the editor interface, and are the most common type of add-on interface. Unlike dialogs, you can continue to interact with the other elements of the editor interface while a sidebar is open. Sidebars have a fixed width, but you can customize their content.

You build add-on sidebars the same way as Apps Script custom sidebars; the general recommended procedure is the following:

  1. Create a script project file that defines your sidebar's HTML structure, CSS, and client-side JavaScript behavior. When defining the sidebar, refer to the editor add-on style guidlines.

  2. In your server-side code where you want the sidebar to open, call HtmlService.createHtmlOutputFromFile(filename) to create an HtmlOutput object representing the sidebar. Alternatively, if you are using templated HTML you can call HtmlService.createTemplateFromFile(filename) to generate a template and then HtmlTemplate.evaluate() to convert it to an HtmlOutput object.

  3. Call Ui.showSidebar(htmlOutput) to display the sidebar using that HtmlOutput.

Sidebars don't suspend the server-side script while they are open. The client-side JavaScript can make asynchronous calls to the server-side using google.script.run() and associated handler functions. For more details, see Client-to-server communication.