Skip to main content

Widgets

This namespace contains functions for creating various widgets that are styled to look and feel native to Gmail.

Namespace methods

isMoleViewTitleBarLightColor()

Returns true if the mole view has a light color title bar as part of Gmail's "new view" styling, and returns false if the Compose has a dark title bar.

showModalView(options)

This creates a ModalView and shows it. You can insert an arbitrary HTMLElement for content of the modal.

ParametersTypeDescription
optionsModalOptionsThe options to configure the returned ModalView.

Returns a ModalView

showMoleView(options)

This creates a MoleView and shows it. A mole view is a modal that is attached to the bottom of the viewport and has minimize and close buttons just like a compose view. Use isMoleViewTitleBarLightColor() to determine the color of the view titlebar if you need to know whether to place light or dark images inside the titlebar.

ParametersTypeDescription
optionsMoleOptionsThe options to configure the returned MoleView.

Returns a MoleView

showDrawerView(options)

This creates a DrawerView and shows it. A drawer view is a panel that slides in from the right side of the screen, and it fades the rest of the screen out. By default, it has a title and a close button.

ParametersTypeDescription
optionsDrawerOptionsThe options to configure the returned DrawerView.

Returns a DrawerView


ModalOptions

The options used to configure a modal when calling Widgets.showModalView().

PropertyTypeDescriptionRequired?Default
elHTMLElementAn HTMLElement representing the content you'd like to put inside the modalYes
chromebooleanWhether to show the close (X) button in the top right of the Modal as well as padding around your content.Notrue
constrainTitleWidthbooleanIf true, then the modal's width is determined solely by the content and not the title's width, and the title's text is line-wrapped if necessary.Nofalse
showCloseButtonbooleanWhen chrome is set to false, this option controls whether a close (X) button should be added to the modal anyway. If chrome is set to true then this property doesn't do anything.Nofalse
titlestringText to show as the title of the modalNo''
buttonsArray<ModalButtonDescriptor>An array of buttons to add to the modal. The UI will be consistent with native Gmail buttons. If none are provided, your el will occupy all of the modal. There may only be one button with a type of PRIMARY_ACTION, see ModalButtonDescriptor docsNo[]

ModalButtonDescriptor

The options to use to configure buttons in a modal.

PropertyTypeDescriptionRequired?Default
textstringThe text displayed in the button.Yes
titlestringText to show when the user hovers the mouse over the button.Yes
onClickfunctionThis is called when the button is clicked.Yes
typestringThere are currently two supported types of modal buttons, PRIMARY_ACTION and SECONDARY action. There may only be one PRIMARY_ACTION button per modal.NoSECONDARY_ACTION
colorstringColor of the modal button. Only 'blue', 'red', or 'green' string values are valid.Nonull
orderHintnumberIf multiple buttons are placed next to each other, then they will be ordered by this value.No0

MoleOptions

The options used to configure a modal when calling Widgets.showMoleView().

PropertyTypeDescriptionRequired?Default
elHTMLElementAn HTMLElement representing the content to put inside the mole view.Yes
titlestringText that the modal should start with as the title.No''
titleElHTMLElementAn HTMLElement to place in the title bar instead of the title text.No
minimizedTitleElHTMLElementAn HTMLElement to place in the title bar when the mole is minimized instead of the title text.No
classNamestringExtra CSS class names to add to the mole widget.No''
titleButtonsArray<MoleButtonDescriptor>An array of buttons to add to the mole widget between the minimize and close buttons in the title bar.No[]
chromebooleanWhen chrome is set to false then the header of the mole is not rendered. This includes the title and mimize/close buttons. This means the app is totally responsible for the look and behavior of the mole, while the SDK is responsible only for the positioning.Notrue

MoleButtonDescriptor

The options to use to configure buttons in a mole.

PropertyTypeDescriptionRequired?Default
titlestringText to show when the user hovers the mouse over the button.Yes
iconUrlstringURL for the icon to show on the button. Should be a local extension file URL or a HTTPS URL. The image will be displayed with a height and width of 24px.Yes
iconClassstringAn optional class to apply to the icon.No
onClickfunctionThis is called when the button is clicked.Yes

DrawerOptions

The options used to configure a drawer when calling Widgets.showDrawerView().

PropertyTypeDescriptionRequired?Default
elHTMLElementAn HTMLElement representing the content you'd like to put inside the drawer. Use the CSS property "flex-grow: 1" on it if you want it to expand to the available space in the drawer.Yes
chromebooleanWhether to show the close (X) button and the title at the top of the drawer.Notrue
titlestringText to show as the title of the drawer. Not shown if chrome is set to false.No
composeViewComposeViewYou can optionally specify a ComposeView to associate with the DrawerView. The ComposeView will be interactable next to the DrawerView instead of being blocked. Using this option will animate the ComposeView into position along with the opening DrawerView unlike the DrawerView.associateComposeView() method.No
closeWithComposebooleanIf this is true, then if any associated ComposeView is closed or otherwise becomes inaccessible, then the DrawerView will close too.Nofalse
matchSidebarContentPanelWidthbooleanWhen true, uses a slimmer drawer that matches the width of the sidebar content panel.Nofalse

ModalView

Represents a modal dialog.

Methods

close()

This closes the modal. Does nothing if already closed.

Events

destroy

Fires when this ModalView instance is closed.

Properties

PropertyTypeDescriptionRequired?Default
destroyedbooleanThis property is set to true once the view is destroyed.Yes

MoleView

Represents a mole view. These are modals attached to the bottom of the viewport, like a compose view.

Methods

close()

This closes the mole view. Does nothing if already closed.

setTitle(text)

This allows the title to be changed.

ParametersTypeDescription
textstring

setMinimized(minimized)

This allows the minimize state to be changed.

ParametersTypeDescription
minimizedbooleanIf true, the mole view will be minimized.

getMinimized()

Returns a boolean of the minimize state

Events

destroy

Fires when this MoleView instance is closed.

minimize

Fires when this MoleView instance is minimized.

restore

Fires when this MoleView instance is restored.

Properties

PropertyTypeDescriptionRequired?Default
destroyedbooleanThis property is set to true once the view is destroyed.Yes

DrawerView

Represents a drawer panel.

Methods

close()

This closes the drawer. Does nothing if already closed.

associateComposeView(composeView, closeWithCompose)

This method allows a compose view to be associated with a pre-existing drawer. The compose view will be usable and shown next to the drawer instead of being hidden behind it.

ParametersTypeDescription
composeViewComposeView
closeWithComposebooleanControls whether the DrawerView should close if the ComposeView is closed or otherwise becomes inaccessible.

disassociateComposeView()

If there is a ComposeView currently associated, this will remove its association and visually place the ComposeView back behind the darkened DrawerView backdrop.

Events

slideAnimationDone

Fires when this DrawerView instance is visible and in position.

closing

Fires when this DrawerView has started closing and animating to off-screen.

destroy

Fires when this DrawerView instance is closed and not visible.

preautoclose

Fires when this DrawerView instance is about to close itself in response to a user clicking outside of the drawer or pressing escape. This event may be canceled in order to stop the drawer from closing itself. You may want to do this if you want to show a confirmation dialog before the drawer closes.

Event propertiesTypeDescription
typestringThis will be "outsideInteraction" if the cause is a click or focus outside of the DrawerView, or "escape" if the cause is the user pressing the Escape key.
causeEventThis is the DOM event that is triggering the DrawerView to auto-close.
cancelfunctionCalling this method will prevent this DrawerView from closing itself.

Properties

PropertyTypeDescriptionRequired?Default
destroyedbooleanThis property is set to true once the view is destroyed.Yes