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.SetCommandState( 
                                        commandId, 
                                        MFiles.CommandLocation.MainMenu,
                                        MFiles.CommandState.CommandState_Active
                                    );
                                    break;

                                // Hiddes all command instances for specific command ID
                                case commands.hideCommand.id:
                                     // Hide the command 
                                    shellFrame.Commands.SetCommandState( 
                                        commandId, 
                                        MFiles.CommandLocation.MainMenu,
                                        MFiles.CommandState.CommandState_Hidden
                                    );
                                    break;

                                // Activates (makes visible) all command instances for specific command ID
                                case commands.showCommand.id:
                                     // Show the command 
                                    shellFrame.Commands.SetCommandState( 
                                        commandId, 
                                        MFiles.MenuLocation.MenuLocation_TopPaneMenu,
                                        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.getCommandState(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.