Custom Tray Menus
For every server you start, there is a corresponding icon in your PC's system tray. In addition to the menu options you get out of the box, you can add in custom menu items. Menus are defined as nested arrays of structs, where each struct represents a single menu item. A menu item can be informational, have an action, or contain sub menus.
You can customize the tray menus for a server via 3 different methods:
The
trayOptions
array in a specific server'sserver.json
file. These menu additions will be specific to that server.The
server.defaults.trayOptions
config setting. These menu additions will be added to every server you startA custom CommandBox Module with an interceptor listening to the
onServerStart
interception point that modifies theserverInfo.trayOptions
array.
Each menu item struct can have the following keys. Only label
is required.
label - This text appears on the menu and is the unique name
image - A custom image file to use for the icon. Relative paths in the
server.json
will be relative to the JSON file Relative paths in the global config will be relative to the web root of the server.disabled - Boolean that greys out menu item and disables any action. Use for informational items.
items - An array that contains a struct of sub menus.
action - This controls what the menu item does when clicked. Possible options are:
openfilesystem - Opens a folder on the file system. Requires
path
to be set as well.openbrowser - Opens a URL in your default browser. Requires
url
to be set as well.stopserver - Stops the current server
run - Runs an arbitrary native command synchronously. Requires
command
to be set as well.runAsync - Runs an arbitrary native command asynchronously Requires
command
to be set as well.runTerminal - Runs an arbitrary native command in a new Terminal window. Requires
command
to be set as well.
path - The file system path to use for the
openfilesystem
action.url - The HTTP URL to use for the
openbrowser
actioncommand - The native command to run for the
run
,runAsync
, orrunTerminal
actions.workingDirectory - The working directory to use for the
run
,runAsync
orrunTerminal
actions.shell - Override the native shell to use on your OS. Defaults to your
nativeShell
config setting.
openfilesystem Example
openbrowser Example
stopserver Example
run Example
Commands executed by the run
action will display their output in a popup window. The PID of the process is available if running on Java 9 or later. Also, there is a button to kill the process, but your mileage may vary. Only use this option to run command line apps that have console output you want to see.
runAsync Example
Commands executed by the runAsync
action work like the run
action except there is no windows to show you the output. This is what you want to use to fire off an app such as an IDE.
runTerminal Example
Commands executed by the runTerminal
action work like the run
action except a new terminal window is opened to run the command. The terminal windows stays open and you can continue to interact with it when the command finishes.
You can customize how your command is run by setting the optional workingDirectory
and shell
properties. If not set, the working directory will be the web root of the server.
Sub Menus
You can nest menus by supplying another array of structs in the items
property of a menu. A menu cannot have an action and have sub menus.
Override Existing Menus
Menu items are layered "on top" of existing options whichs mean you can add new sub menu items to an existing top level menu. You can even override the action or image of a built-in menu. Menu items are registered in this order:
Built-in menus
Config setting server defaults
server.json trayOptions
onServerStart interceptor
This example server.json
will add a new sub menu into the existing "Open..." top level menu.
There is no way to remove existing menu items via your config settings or server.json
. To do that, you'd need to directly manipulate the trayOptions
array in an interceptor.
Last updated