Dashboards in the User Interface Extensibility Framework

Dashboards contain user interfaces that can be shown to the user as required.

Dashboard content

Dashboard content is held within an HTML file. This HTML file may refer to external static resources such as CSS files, JavaScript files or image files. These files are typically packaged inside the User Interface Framework application, although they can be loaded from remote sources if required.

All referenced files must be static; no server-side code (e.g. PHP or ASP.NET) can execute within a User Interface Extensibility Framework application. Any preprocessing required (e.g. SASS or LESS) must be processed before the UIX is run.

Showing and hiding dashboards

More information on using dashboards is available in the M-Files UI Extensibility Framework documentation site.

Dashboards are shown in one of a small number of locations within the M-Files client:

When a dashboard is shown, a JavaScript object can be passed to the dashboard for it to use. This object may contain any information that is of use. For example: you may decide to pass the currently-selected object(s) to the dashboard for it to process.

Within a custom tab

Most dashboards are shown within their own custom tabs on the right-hand-section, alongside “Metadata” and “Preview”.

Dashboards are shown by calling IShellPaneTab.ShowDashboard. This takes two arguments:

// This is the ID of the dashboard, as declared in the appdef.xml file.
var dashboardId = "myDashboardId";

// This is the data (empty) to send to the dashboard.
var customData = {};

// Show the dashboard in the current tab.
// Note: This assumes an IShellPaneTab reference.
shellPaneTab.ShowDashboard(dashboardId, customData);

As a pop-up window

Dashboards can be shown within a pop-up window by calling IShellFrame.ShowPopupDashboard, IDashboard.ShowPopupDashboard, or IShellUI.ShowPopupDashboard, or IVaultUI.ShowPopupDashboard. All methods take three arguments:

// This is the ID of the dashboard, as declared in the appdef.xml file.
var dashboardId = "myDashboardId";

// This is the data (empty) to send to the dashboard.
var customData = {};

// Show the dashboard using the current IShellUI (not modal).
// Note: This assumes an IShellUI reference.
shellUI.ShowPopupDashboard(dashboardId, false, customData);

Replacing the current listing

In some situations, it may make sense to show a dashboard within the main listing area within M-Files; i.e. the area where the views and groupings are shown. The listing area can be replaced with the content of a dashboard by calling IShellFrame.ShowDashboard. This takes two arguments:

// This is the ID of the dashboard, as declared in the appdef.xml file.
var dashboardId = "myDashboardId";

// This is the data (empty) to send to the dashboard.
var customData = {};

// Show the dashboard in the listing area.
// Note: This assumes an IShellFrame reference.
shellFrame.ShowDashboard(dashboardId, customData);

To revert the listing area to showing the default content, call IShellFrame.ShowDefaultContent.

Replacing the right or bottom panes

In some situations, it may make sense to replace the right and bottom panes. The right pane can be replaced with the content of a dashboard by calling IShellPaneContainer.ShowDashboard. This takes two arguments:

// This is the ID of the dashboard, as declared in the appdef.xml file.
var dashboardId = "myDashboardId";

// This is the data (empty) to send to the dashboard.
var customData = {};

// Show the dashboard in the right pane.
// Note: This assumes an IShellFrame reference.
shellFrame.RightPane.ShowDashboard(dashboardId, customData);

// Show the dashboard in the bottom pane.
// Note: This assumes an IShellFrame reference.
shellFrame.BottomPane.ShowDashboard(dashboardId, customData);

Replacing the right-pane implicitly creates a tab entitled “Application”, into which the dashboard is loaded. The bottom pane may not be shown by default, but can be made visible by setting BottomPane.Visible to true.

Tips and tricks

Dashboard tab icons

This functionality is available in M-Files Desktop clients 20.3 and higher.

When a tab is added to the M-Files Desktop client it will, by default, be shown with the general tab icon (four squares, arranged in a 2x2 grid). This can be altered if the tab is showing a dashboard. To do this you will need two files named icon.png and icon-selected.png (both 32px by 32px). These files must be placed within a folder named the same as the dashboard ID. icon.png will be shown when the tab is unselected, icon-selected.png will be shown when the tab is selected.

For example, for this appdef.xml file the files would be located in a folder named my-dashboard:

...
<dashboards>
	<dashboard id="my-dashboard">
		<content>my-dashboard/my-dashboard.html</content>
	</dashboard>
</dashboards>
...

This functionality cannot be used with tabs that do not show dashboards, or do not yet have dashboards loaded.

Passing content to and from dashboards

Passing content from modules to dashboards

When showing a dashboard, a custom data object can be passed to the dashboard. This custom data object can then be read by the dashboard and processed.

From within the module, call ShowDashboard or ShowPopupDashboard as appropriate, passing the custom data. In this scenario I’ve passed a simple string:

shellFrame.RightPane.ShowDashboard("myDashboardId", "hello world");

From within the dashboard, create a function named OnNewDashboard to react when the dashboard is shown. This will be passed a IDashboard object, which the CustomData can be read from:

<html>
<head>
<title>Dashboard example</title>
</head>
<body>
<p>The message passed was: <span id="message"></span>.</p>

<script type="text/javascript">
function OnNewDashboard( dashboard )
{
	// Retrieve the dashboard custom data and display it on-screen.
	document.getElementById("message").innerHTML = dashboard.CustomData;
}
</script>
</body>
</html>

Executing a function declared within a module from within a dashboard

The custom data object passed to the dashboard can contain simple data types, complex objects (e.g. M-Files API objects), functions, or almost any other type of content. Passing a function to the dashboard allows that function to be used as a callback when certain events occur within the dashboard.

From within the module, call ShowDashboard or ShowPopupDashboard as appropriate, passing a custom data object containing a function:

// Create the custom data object.
var customDataObject = {
	// Create a property named "myFunction" and assign it the function to call.
	// This function defines one parameter, but it could have any number.
	myFunction: function(param)
	{
		// Show the message.
		shellFrame.ShowMessage(param);
	}
};

// Show the dashboard.
shellFrame.RightPane.ShowDashboard("myDashboardId", customDataObject);

From within the dashboard, store a reference to the function passed, and call it when you need to execute the code that was declared within the module. In this scenario, clicking the button will cause the module to show a message box with the text from the input:

<html>
<head>
<title>Dashboard example</title>
</head>
<body>

<div>
	Text to send: <input type="text" id="textToSend" />
</div>
<div>
	<button onclick="return sendContent(event);">Send</button>
</div>

<script type="text/javascript">
var myFunctionReference = null;
function OnNewDashboard( dashboard )
{
	// Hold a reference to the callback function.
	myFunctionReference = dashboard.CustomData.myFunction;
}
function sendContent(e)
{
	// Get the text to send.
	var text = document.getElementById("textToSend").value;

	// Call the function.
	myFunctionReference(text);

	return false;
}
</script>
</body>
</html>