Testing and Developing

Runtime Environment

The runtime environment of the UI Extension is inside sandboxed <iframe /> and communication between the M-Files Client and UI Extension is done internally using postMessage where the calls are serialized using Structured Clone algorithm.

When a call to an UI Extension Object is done, for example

const commandId = await shellFrame.Commands.CreateCustomCommand(name);

The call is serialized into a postMessage message using MESP protocol (M-Files Extension Sandbox Protocol). It is possible to enable logging of the postMessage calls if you want to observe exactly what is going on during execution of specific command.

The global variables, like Enumerations are bound into MFiles variable only after the initialization message.

tip

For a complete reference of the MFiles global object and all its namespaces, see the MFiles Global Object documentation.

The MFiles Global Object

The MFiles global variable is your primary interface for accessing enumerations and utility functions. It includes:

Namespace	Description	Example
MFiles.Event	Event type constants	MFiles.Event.Started, MFiles.Event.NewShellFrame
MFiles.MenuLocation	Menu location constants	MFiles.MenuLocation.MenuLocation_TopPaneMenu
MFiles.CommandState	Command state constants	MFiles.CommandState.CommandState_Active
MFiles.CommandLocation	Command location constants	MFiles.CommandLocation.MainMenu
MFiles.BuiltinCommand	Built-in command IDs	MFiles.BuiltinCommand.NewObject
MFiles.VaultEnums	Vault/gRPC API enumerations	MFiles.VaultEnums.ConditionType.CONDITION_TYPE_EQUAL
MFiles.*	ICommonFunctions methods	MFiles.GetAccentColor(), MFiles.ShowMessage()

See: MFiles Global Object Reference

Debugging from Developer Tools

From the browser developer tools you can select the IFRAME and observe the global variables installed there.

You can inspect the MFiles object to see all available enumerations and methods:

// In browser console, inspect the MFiles object
console.log(MFiles);

// List all available Event types
console.log(Object.keys(MFiles.Event));

// List all available VaultEnums
console.log(Object.keys(MFiles.VaultEnums));

Calling ICommonFunctions

MFiles global variable includes enumerations and also the ICommonFunctions properties and methods.

// Call ICommonFunctions.GetAccentColor()
await MFiles.GetAccentColor() // returns "#006eef"

// Save a key into webstorage
await MFiles.WriteToWebStorage("key", "value")

// Read from webstorage
const value = await MFiles.ReadFromWebStorage("key")

Accessing the Dashboard object

In the dashboard code you can access the Dashboard object using _MESP global variable.

// retrieve the active dashboard object inside a dashboard IFRAME
const dashboard = _MESP.ApplicationObjects.Dashboard;

// Create a popup dashboard with ID "my-dashboard"
await dashboard.ShellFrame.ShowPopupDashboard("my-dashboard", {});

Enable postMessage logging

If you want to enable logging of the postMessage commands into the Developer Tools console you can turn that on inside the UI Extension application using

// Enable logging of postMessage calls into console
window._MESP.logLevel = "all";