CreateCustomCommand
Description
The CreateCustomCommand function is a functionality within the M-Files UI Extension framework designed for creating custom commands dynamically.
This function enables developers to define and generate new custom commands programmatically.
It accepts the name of the command as a parameter, and it returns a unique identifier (ID) associated with the newly created command.
The created command ID can then be consumed for example by
- AddCustomCommandToMenu to create a new Menu item which executes the command
- ExecuteCommand to directly execute the command inside the application with optional command arguments
- CreateSubMenuItem to create submenu commands.
You can control the visibility of the command in M-Files menus using SetCommandState.
Command can be removed using DeleteCustomCommand.
Syntax
// Create a new custom command using IShellFrame instance.
const commandId = await shellFrame.Commands.CreateCustomCommand(name);
Parameters
| Name | Optionality | Type | Description |
|---|---|---|---|
| commandName | Required | string | The custom command's name. |
Return type
| Type | Description |
|---|---|
Promise < number > | Returns the command id of the created custom command. |
Example
This JavaScript code is a UI Extension for M-Files, creating custom commands such as "Hello World" and providing functionality to dynamically show, hide, and remove these commands from the top menu based on user interactions within the M-Files shell.
// Called when the UI Extension starts
function OnNewShellUI(shellUI) {
// Wait for the ShellFrame to be created.
shellUI.Events.Register(
MFiles.Event.NewShellFrame,
async (shellFrame) => {
// Wait for the shellframe to start
shellFrame.Events.Register(
MFiles.Event.Started,
async () => {
// Create a new custom command and menu item for the command
const createCommand = async ( name: string ) => {
// Create a new custom command
const commandId = await shellFrame.Commands.CreateCustomCommand(name);
// Add the command to the top menu
const menuItemId = await shellFrame.Commands.AddCustomCommandToMenu(
// Command ID
commands.exampleCommand,
// Menulocation
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
// Priority of the command
1
);
// Return a data structure containing essential information about the commands
return {
id: commandId, // ID of the command
menuItemId // Menu item ID, can be used to add sub menus to this menu item.
}
}
// Create an Example command and a set of sample commands to control it's visibility
const commands = {
// This is the sample command
exampleCommand : await createCommand("Hello World"),
// These commands control the state of the example command
addCommand: await createCommand("Add Command To Menu"),
deleteCustomCommand: await createCommand("Delete Command")
hideCommand: await createCommand("Hide Command"),
showCommand: await createCommand("Activate Command"),
executeCommand: await createCommand("Execute Command"),
getCommandName: await createCommand("Get Name"),
getCommandState: await createCommand("Get Command State"),
removeCommandFromMenu: await createCommand("Remove From Menu"),
removeCommand: await createCommand("Remove Command")
}
// Add the command to the top menu
const menuItemId = await shellFrame.Commands.AddCustomCommandToMenu(
commands.exampleCommand,
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
1 // Priority of the command
);
// Listen for the custom commands.
shellFrame.Commands.Events.Register(
// Listen for the CustomCommand events.
MFiles.Event.CustomCommand,
// Each command has ID and optional data provided with it.
( commandId, data ) => {
// Respond to the command if custom command sent by the application
switch( commandId ) {
// Run the Example command
case commands.exampleCommand.id:
shellFrame.ShowMessage( "Hello World!" );
break;
// Add the new menuitem which runs the example command
case commands.addCommand.id:
await shellFrame.Commands.AddCustomCommandToMenu(
commands.exampleCommand,
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
1 // Priority of the command
);
break;
// Removes the command from particular menu
case commands.removeCommandFromMenu.id:
await shellFrame.Commands.RemoveCustomCommandFromMenu(
commands.exampleCommand,
MFiles.MenuLocation.MenuLocation_TopPaneMenu
);
break;
// Deletes the command permanently
case commands.deleteCommand.id:
shellFrame.Commands.DeleteCustomCommand(
commandId
);
break;
// Hides command instance for the specified command ID from the main menu
case commands.hideCommand.id:
// Hide the command
shellFrame.Commands.SetCommandState(
commandId,
MFiles.CommandLocation.MainMenu,
MFiles.CommandState.CommandState_Hidden
);
break;
// Activates (makes visible) command instance for the specified command ID in the main menu
case commands.showCommand.id:
// Show the command
shellFrame.Commands.SetCommandState(
commandId,
MFiles.CommandLocation.MainMenu,
MFiles.CommandState.CommandState_Active
);
break;
// Get the command name
case commands.getCommandName.id:
const name = await shellFrame.Commands.GetCommandName(commands.exampleCommand.id);
shellFrame.ShowMessage( name );
break;
// Get the Command State
case commands.getCommandState.id:
// NOTE: the MFiles.CommandLocation.MainMenu must be used to get state of items added to the Top Menu
const commandState = await shellFrame.Commands.SetCommandState(commands.exampleCommand.id, MFiles.CommandLocation.MainMenu );
shellFrame.ShowMessage( `Command state: ${commandState}` );
break;
}
}
);
}
)
}
)
}
This code is essentially setting up a simple UI extension with custom commands that can be triggered from the top menu, and it allows dynamic control over the visibility of these commands based on user interactions.
Exceptions
ArgumentError - When commandName is null or undefined.