Skip to content

API - Menu

Allows you to interact with the user interface.

When extending BasePlugin, these functions can be accessed via this.menus.*

When extending BaseComponent, these functions can be accessed via this.plugin.menus.*

Functions

alert(text, title, icon='info') : Promise<void>

Displays a popup alert to the user.

Field Type Description Example
text string Message to show the user 'Hello, World!'
title string Title to display at the top of the alert 'Hey'
icon string Icon to display in the alert. Accepted values are 'info', 'success', 'question', 'error' and 'warning' 'success'
Example Use 
// -- When extending BasePlugin
await this.menus.alert('Hello, World!', 'Hi', 'success')

// -- When extending BaseComponent
await this.plugin.menus.alert('Hello, World!', 'Hi', 'success')

prompt(options) : Promise<string | undefined>

Displays a popup alert to the user with a text field for the user to enter some information.

Returns the text the user entered, if they clicked the "OK" button, or undefined if they clicked the "Cancel" button or clicked outside of the popup area.

Properties available for the options parameter

Field Type Description Example
icon string Icon to display in the alert. Accepted values are 'info', 'success', 'question', 'error' and 'warning' 'info'
title string Title to display at the top of the prompt 'Welcome'
text string Message to show the user 'Please enter your name below'
inputType string Type of input area to show. Available options are: 'text', 'textarea', 'email', 'password', 'number', 'tel' and 'url' 'text'
initialValue string Initial value to display in the input area 'My Name'
placeholder string Placeholder text to show in the input area 'Type something...'
Example Use 
// -- When extending BasePlugin
const value = await this.menus.prompt({
    icon: 'info',
    title: 'Welcome!',
    text: 'Please enter your name below',
    inputType: 'text',
    initialValue: 'My Name',
    placeholder: 'Type something...'
})
console.log(value) // => 'Kyle'

// -- When extending BaseComponent
const value = await this.plugin.menus.prompt({
    icon: 'info',
    title: 'Welcome!',
    text: 'Please enter your name below',
    inputType: 'text',
    initialValue: 'My Name',
    placeholder: 'Type something...'
})
console.log(value) // => 'Kyle'

toast(options) : string

Displays a toast message that appears at the bottom of the screen.

Properties available for the options parameter

Field Type Description Example
icon string URL for an icon to display this.paths.absolute('./icon.svg')
text string Message to show the user 'Hello!'
textColor string Color of the message text '#2DCA8C'
buttonColor string Color of the action and cancel button text '#FFFFFF'
buttonText string Text to display on a button on the right-hand side 'Enable'
buttonAction Function Function to execute when the button is clicked () => { console.log('clicked') }
buttonCancelText string Text to display on a cancel button on the right-hand side 'Disable'
buttonCancelAction Function Function to execute when the cancel button is clicked () => { console.log('clicked cancel') }
duration number Number of milliseconds to display the toast for. Default is 15000 ms (15 seconds). 15000
Example Use 
// -- When extending BasePlugin
const toastID = this.menus.toast({
    icon: this.paths.absolute('./icon.svg'),
    text: 'Hello!',
    textColor: '#2DCA8C',
    buttonColor: '#FFFFFF',
    buttonText: 'Enable',
    buttonAction: () => { console.log('clicked') },
    buttonCancelText: 'Disable',
    buttonCancelAction: () => { console.log('clicked cancel') },
    duration: 15000
})
console.log(toastID) // => 7

// -- When extending BaseComponent
const toastID = this.plugin.menus.toast({
    icon: this.paths.absolute('./icon.svg'),
    text: 'Hello!',
    textColor: '#2DCA8C',
    buttonColor: '#FFFFFF',
    buttonText: 'Enable',
    buttonAction: () => { console.log('clicked') },
    buttonCancelText: 'Disable',
    buttonCancelAction: () => { console.log('clicked cancel') },
    duration: 15000
})
console.log(toastID) // => 7

postMessage(data) : void

Sends a message to any open panels.

Field Type Description Example
data object Data to send { pi: 3.14159 }
Example Use 
// -- When extending BasePlugin
this.menus.postMessage({ pi: 3.14159 })

// -- When extending BaseComponent
this.plugin.menus.postMessage({ pi: 3.14159 })

register(settings) : string

Adds a menu item and returns the ID as a string.

Properties available for the settings parameter

Property Type Default Description
id string generated Identifier used for this menu item. If specified and a menu with this identifier already exists, it will be updated instead
title string "" Title of the menu item
icon any null Icon to display in the menu item. You can use this.paths.absolute('./path/to/icon.svg') as the value for a local icon file
color string icon color Color of the icon. If set, will replace the icon's default color with this color
text string "Text" Text to display under the icon
order number 0 Used to sort the menu items. Lowest to highest is in left to right order, so order: 1 will come before order: 2 when looking from left to right
adminOnly boolean false true to only display this item if the user is an admin, false otherwise
inAccordion boolean false true to indicate that the menu item should appear in the accordion, false otherwise
action Function () => {} An optional function which is executed when the menu item is clicked. The first parameter passed to the function is context information, i.e. the user who was selected, etc.
section string "controls" Determines where this menu item appears. Available options are:
  • 'controls' : Displays the menu item in the bottom menu bar. If a panel is specified, it will open in the accordion (if inAccordion is true) or as a separate panel on the right-hand side of the screen (if inAccordion is false)
  • 'usermenu' : Displays the menu item as an action in the panel that appears when clicking on a user. See currentUser and otherUsers as well
  • 'infopanel' : Displays the panel permanently as a transparent overlay in the top-right. Good place for information such as tasks to complete, etc.
  • 'overlay-top' : Displays the panel permanently as a transparent overlay along the top of the app. This obstructs user controls, so it should only be used for short alerts before being removed
  • 'bottom-accordion' : Displays a panel that will permanently appear at the bottom of the accordion
  • 'plugin-settings' : Displays the panel when a user clicks the "Settings" button next to a plugin. Only one of this type should be registered per plugin. Only accessible to admin users
  • 'start-screen' : Adds this panel as an option under File -> Settings -> Welcome Screen. The selected screen can be displayed instead of the normal start screen. Only accessible to admin users. NOTE: This screen is loaded before any plugins are loaded. It will receive messages indicating the load progress and it can hide or "complete" the loading by sending window.parent.postMessage({ action: "hide" }, '*')
  • 'file-menu' : Displays the menu item under the File dropdown in the top admin menu bar. Only accessible to admin users
  • 'admin-panel' : Displays the menu item in the container shown when clicking the "Admin" button in the bottom menu bar. Only accessible to admin users
currentUser boolean false If true and section === 'usermenu', the menu item appears on the current user's menu panel
otherUsers boolean true If true and section === 'usermenu', the menu item appears on other user's menu panels
panel object {} Object describing a panel to display when this menu item is clicked. See below for all available properties

Properties available for the panel parameter

Property Type Description Example
iframeURL string URL to display in the panel 'https://open.spotify.com/embed/playlist/0vC2B4CRTQfTu899Jh0Cxf'
width number | string Width the panel should be. When given a number, pixels are used 300 or '300px'
height number | string Height the panel should be. When given a number, pixels are used 300 or '300px' Note that both width and height are only a suggestion and may be changed.
fields object[] Shows plugin settings that can be changed. Only valid when section === 'plugin-settings'. See below for all available properties for each field object inside this array [{ id: 'hi', name: 'Text', help: 'Enter some text', type: 'text' }]

Properties available for the fields property

Property Type Description Example
id string Identifier for the editable settings 'my-plugin-settings'
name string Name of the field 'Score Increase'
help string Additional information about the field 'How many points to add to score'
type string Determines the type of input to show. Available options are:
  • 'text' : Shows a one-line text input
  • 'textarea' : Shows a multi-line text input
  • 'number' : Shows an input that only accepts numbers
  • 'select' : Shows a dropdown of items that can be chosen
  • 'checkbox' : Shows a checkbox that can either be enabled or disabled
  • 'color' : Shows a color picker that returns a hexadecimal value
  • 'label' : Shows a text label
  • 'section' : Shows a big text label, used mainly to group inputs into sections
 'number'
default string Default value to show when type === 'color' or type === 'number' '#FA5252'
value string Text to show when type === 'label' 'I am a label'
values string[] Array of possible values to select from when type === 'select' ['Facebook', 'Amazon', 'Apple', 'Netflix', 'Google']
Example Use 
// -- When extending BasePlugin
const menuID = this.menus.register({
    id: 'my-plugin',
    title: 'Hello World!',
    icon: this.paths.absolute('./icon.svg'),
    text: 'Hello',
    order: 3,
    section: 'controls',
    adminOnly: false,
    inAccordion: false,
    action: null,
    currentUser: false,
    otherUsers: false,
    panel: {
        iframeURL: this.paths.absolute('./my-panel.html')
    }
})
console.log(menuID) // => 'my-plugin'

// -- When extending BaseComponent
const menuID = this.plugin.menus.register({
    id: 'my-plugin',
    title: 'Hello World!',
    icon: this.paths.absolute('./icon.svg'),
    text: 'Hello',
    order: 3,
    section: 'controls',
    adminOnly: false,
    inAccordion: false,
    action: null,
    currentUser: false,
    otherUsers: false,
    panel: {
        iframeURL: this.paths.absolute('./my-panel.html')
    }
})
console.log(menuID) // => 'my-plugin'

displayPopup(settings) : string

Shows a popup UI. All options are the same as for the register() call.

Example Use 
this.menus.displayPopup({
    title: 'My Popup',
    panel: {
        iframeURL: this.paths.absolute('./my-panel.html'),
        width: 400,
        height: 600
    }
})

unregister(id) : void

Unregisters a menu item.

Field Type Description Example
id string Identifier of the menu item to unregister 'my-plugin'
Example Use 
// -- When extending BasePlugin
this.menus.unregister('my-plugin')

// -- When extending BaseComponent
this.plugin.menus.unregister('my-plugin')
Back to top