For most Editor Add-on, 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 interface, 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:
- 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 guidelines.
- In your server-side code where you want the dialog to open, call
HtmlService.createHtmlOutputFromFile(filename)
to create anHtmlOutput
object representing the dialog. Alternatively, if you are using templated HTML you can callHtmlService.createTemplateFromFile(filename)
to generate a template and thenHtmlTemplate.evaluate()
to convert it to anHtmlOutput
object. - Call
Ui.showModalDialog(htmlOutput, dialogTitle)
to display the dialog using thatHtmlOutput
.
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
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:
- 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 guidelines.
In your server-side code where you want the sidebar to open, call
HtmlService.createHtmlOutputFromFile(filename)
to create anHtmlOutput
object representing the sidebar. Alternatively, if you are using templated HTML you can callHtmlService.createTemplateFromFile(filename)
to generate a template and thenHtmlTemplate.evaluate()
to convert it to anHtmlOutput
object.Call
Ui.showSidebar(htmlOutput)
to display the sidebar using thatHtmlOutput
.
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.