Skip to main content

ButterBar

This namespace contains methods for showing informative messages to the user. In Gmail this is a small yellow "butter bar" overlay near the top.

Namespace methods#

showMessage(options)#

Spawns a new message.

ParametersTypeDescription
optionsMessageDescriptormessage options

Returns an Object that contains a destroy method that can be called to remove the message.

showLoading(options)#

Spawns a "Loading..." message that stays until it's destroyed.

ParametersTypeDescription
optionsLoadingMessageDescriptormessage options

Returns an Object which has a destroy method that can be called to remove the message.

showError(options)#

Spawns a new error message. Error messages also have a default priority of 100 instead of 0 (as in the case of ButterBar.showMessage).

ParametersTypeDescription
optionsMessageDescriptormessage options

Returns an Object which contains a destroy method that can be called to remove the message.

showSaving(options)#

Spawns a "Saving..." message that stays until it's removed.

ParametersTypeDescription
optionsSavingMessageDescriptormessage options

Returns an Object which has a resolve method that can be called to show a "Saved" confirmation message, and a reject method that can be called to remove the message immediately with no confirmation.

hideMessage(messageKey)#

Hides all messages created by the same app with the given messageKey.

ParametersTypeDescription
messageKeyObjectthe key of the message to hide

hideGmailMessage()#

Hides any messages currently displayed by Gmail.

--

MessageDescriptor#

This type is used to describe a message for ButterBar to show.

PropertyTypeDescriptionRequired?Default
textstringText to show. Either the text property or the html property must be passed.No
htmlstringString to use as the innerHTML of the ButterBar instead of using the given text.No
elHTMLElementHTML element to insert into the ButterBar instead of using the given text.No
classNamestringString to add as a css class to the ButterBar container element.No
prioritynumberMessages with lower priorities won't interrupt a currently displayed message.No0
timenumberNumber of milliseconds the message is displayed before going away on its own.No15000
hideOnViewChangedbooleanIf true, the message will immediately disappear if the user navigates to another route view.Notrue
persistentbooleanWhether this message should re-appear after being interrupted by another message.Nofalse
messageKeyObjectIf a new message has the same messageKey as the current message, then the current message will always be destroyed, regardless of its priority.No
buttonsArray<MessageButtonDescriptor>An array of buttons to support functionality in addition to the preview functionalityNo

--

MessageButtonDescriptor#

This type is used to describe the buttons for ButterBar to show.

PropertyTypeDescriptionRequired?Default
onClickfunction(event)This is called when a button is clicked and gets passed an event object.Yes
titlestringText of the button.Yes

--

LoadingMessageDescriptor#

This type is used to describe the messages for ButterBar.showLoading to show

PropertyTypeDescriptionRequired?Default
textstringText shown while the loading is ongoing.No'Loading...'
htmlstringString to use as the innerHTML of the ButterBar instead of using the given text.No
elHTMLElementHTML element to insert into the ButterBar instead of using the given text.No
classNamestringString to add as a css class to the ButterBar container element.No
prioritynumberMessages with lower priorities won't interrupt a currently displayed message. Loading messages default to a lower priority than other message types.No-3
hideOnViewChangedbooleanIf true, the message will immediately disappear if the user navigates to another route view.Notrue
persistentbooleanWhether this message should re-appear after being interrupted by another message.Notrue
messageKeyObjectIf a new message has the same messageKey as the current message, then the current message will always be destroyed, regardless of its priority. Sets the messageKey of both the initial message and the confirmation message.No

--

SavingMessageDescriptor#

This type is used to describe the messages for ButterBar.showSaving to show

PropertyTypeDescriptionRequired?Default
textstringText shown while the saving is ongoing.No'Saving...'
confirmationTextstringText shown when the save is complete.No'Saved'
confirmationTimenumberNumber of milliseconds the confirmation text is shown.No1000
showConfirmationbooleanWhether or not to show the confirmation message when the initial message is resolved.Notrue
htmlstringString to use as the innerHTML of the ButterBar instead of using the given text.No
elHTMLElementHTML element to insert into the ButterBar instead of using the given text.No
classNamestringString to add as a css class to the ButterBar container element.No
prioritynumberMessages with lower priorities won't interrupt a currently displayed message. Loading messages default to a lower priority than other message types.No-3
hideOnViewChangedbooleanIf true, the message will immediately disappear if the user navigates to another route view.Notrue
persistentbooleanWhether this message should re-appear after being interrupted by another message.Notrue
messageKeyObjectIf a new message has the same messageKey as the current message, then the current message will always be destroyed, regardless of its priority. Sets the messageKey of both the initial message and the confirmation message.No