Skip to main content

MFiles Global Object

The MFiles global object is available in your UI Extension code after initialization. It provides access to enumerations, utility functions, and the Vault API enums.

info

The MFiles global object is only available after the UI Extension has been initialized. It is automatically injected into your extension's iframe context.

Overview​

The MFiles global object contains:

Namespace/PropertyDescription
MFiles.EventUI Extension event type constants
MFiles.MenuLocationMenu location constants for custom commands
MFiles.CommandStateCommand state constants (active, inactive, hidden)
MFiles.CommandLocationCommand location constants
MFiles.BuiltinCommandBuilt-in M-Files command identifiers
MFiles.VaultEnumsgRPC/Vault API enumerations
MFiles.* (ICommonFunctions)Utility methods from ICommonFunctions

UI Extension Enumerations​

These enumerations are used when working with UI Extension features like events, commands, and menus.

MFiles.Event​

Event type constants used when registering event handlers.

// Register a handler for the Started event
shellUI.Events.Register(MFiles.Event.Started, async () => {
    console.log("ShellUI started");
});

// Register a handler for NewShellFrame event
shellUI.Events.Register(MFiles.Event.NewShellFrame, async (shellFrame) => {
    console.log("New shell frame created");
});

// Register a handler for custom commands
shellFrame.Commands.Events.Register(MFiles.Event.CustomCommand, async (commandId) => {
    console.log("Custom command executed:", commandId);
});

See: Event Enumeration

MFiles.MenuLocation​

Constants for specifying where custom commands appear in menus.

// Add command to the top pane menu
await shellFrame.Commands.AddCustomCommandToMenu(
    commandId, 
    MFiles.MenuLocation.MenuLocation_TopPaneMenu, 
    0
);

See: MenuLocation Enumeration

MFiles.CommandState​

Constants for setting the state of custom commands.

// Set command as active (enabled)
await shellFrame.Commands.SetCommandState(
    commandId, 
    MFiles.CommandLocation.MainMenu, 
    MFiles.CommandState.CommandState_Active
);

// Hide a command
await shellFrame.Commands.SetCommandState(
    commandId, 
    MFiles.CommandLocation.MainMenu, 
    MFiles.CommandState.CommandState_Hidden
);

See: CommandState Enumeration

MFiles.CommandLocation​

Constants for specifying command locations.

await shellFrame.Commands.SetCommandState(
    commandId, 
    MFiles.CommandLocation.MainMenu, 
    MFiles.CommandState.CommandState_Active
);

See: CommandLocation Enumeration

MFiles.BuiltinCommand​

Identifiers for built-in M-Files commands.

// Execute the built-in "New Object" command
await shellFrame.Commands.ExecuteCommand(MFiles.BuiltinCommand.NewObject, null);

See: BuiltinCommand Enumeration

Vault API Enumerations (MFiles.VaultEnums)​

The MFiles.VaultEnums namespace contains enumerations used when working with the Vault gRPC API. These are essential when constructing search conditions, working with property values, and interacting with vault data.

Common VaultEnums​

These are some of the most commonly used enumerations. For the complete list, see gRPC Enums Reference.

EnumerationPurpose
MFiles.VaultEnums.ConditionTypeSearch condition types (equal, contains, etc.)
MFiles.VaultEnums.DatatypeProperty data types
MFiles.VaultEnums.ExpressionTypeSearch expression types
MFiles.VaultEnums.DataFunctionData functions for search conditions
MFiles.VaultEnums.FolderTypeFolder type constants
MFiles.VaultEnums.StatusTypeStatus type constants
MFiles.VaultEnums.ObjectVersionDataRequestVersionTypeVersion request types

Example: Building a Search Condition​

// Search for documents containing "invoice" in any field
const searchCondition = {
    expression: {
        type: MFiles.VaultEnums.ExpressionType.EXPRESSION_TYPE_ANY_FIELD
    },
    type: MFiles.VaultEnums.ConditionType.CONDITION_TYPE_CONTAINS,
    typedValue: {
        value: "invoice",
        datatype: {
            type: MFiles.VaultEnums.Datatype.DATATYPE_TEXT
        }
    }
};

Example: Creating a Search Folder​

const searchFolder = {
    type: MFiles.VaultEnums.FolderType.FOLDER_TYPE_SEARCH_FOLDER,
    searchDef: {
        conditions: [
            {
                expression: {
                    propertyValue: {
                        property_def: 100,
                        data_function: MFiles.VaultEnums.DataFunction.DATA_FUNCTION_NO_OP
                    },
                    type: MFiles.VaultEnums.ExpressionType.EXPRESSION_TYPE_PROPERTY_VALUE
                },
                type: MFiles.VaultEnums.ConditionType.CONDITION_TYPE_EQUAL,
                typedValue: {
                    value: true,
                    datatype: {
                        type: MFiles.VaultEnums.Datatype.DATATYPE_BOOLEAN
                    }
                }
            }
        ]
    }
};

ICommonFunctions Methods​

The MFiles global object also includes methods from ICommonFunctions. These provide utility functions that can be called directly on the MFiles object.

Web Storage​

// Save data to web storage
await MFiles.WriteToWebStorage("myKey", "myValue");

// Read data from web storage
const value = await MFiles.ReadFromWebStorage("myKey");

UI Utilities​

// Get the current accent color
const accentColor = await MFiles.GetAccentColor(); // returns "#006eef"

// Show a message box
await MFiles.ShowMessage("Hello World!");

// Report an exception
await MFiles.ReportException(error);

Vault Access​

// Get current vault GUID
const vaultGuid = await MFiles.GetVaultGuid();

Complete Example​

Here's a complete example showing various MFiles global object usage:

// main.js - Entry point of a UI Extension

async function OnNewShellUI(shellUI) {
    // Register for the Started event
    shellUI.Events.Register(MFiles.Event.Started, async () => {
        console.log("ShellUI started");
        
        // Read a stored preference
        const lastView = await MFiles.ReadFromWebStorage("lastView");
        console.log("Last view:", lastView);
    });

    // Register for new shell frames
    shellUI.Events.Register(MFiles.Event.NewShellFrame, async (shellFrame) => {
        await OnNewShellFrame(shellFrame);
    });
}

async function OnNewShellFrame(shellFrame) {
    // Wait for the shell frame to start
    shellFrame.Events.Register(MFiles.Event.Started, async () => {
        
        // Create a custom command
        const commandId = await shellFrame.Commands.CreateCustomCommand("My Command");
        
        // Add to menu
        await shellFrame.Commands.AddCustomCommandToMenu(
            commandId, 
            MFiles.MenuLocation.MenuLocation_TopPaneMenu, 
            0
        );
        
        // Set command as active
        await shellFrame.Commands.SetCommandState(
            commandId, 
            MFiles.CommandLocation.MainMenu, 
            MFiles.CommandState.CommandState_Active
        );
        
        // Handle command execution
        shellFrame.Commands.Events.Register(MFiles.Event.CustomCommand, async (id) => {
            if (id === commandId) {
                await MFiles.ShowMessage("Custom command executed!");
            }
        });
    });
}

See Also​