M-Files UI Extensibility Framework
Using Dashboards
M-Files UI Extensibility Framework > Technical Articles > Using Dashboards

Defining a Dashboard

Applications with UI accessibility can use dashboards to present user interfaces that are written with HTML and JScript. The dashboard is displayed in a separate window that is either a popup window or integrated child window of the M-Files client.

In order to include a dashboard in an application, a named dashboard implementation must be included in the appdef.xml file. The picture below illustrates how a single dashboard is declared in an appdef.xml file. The dashboard implementation is in sampledashboard.htm file, which needs to be located in same folder as appdef.xml. The dashboard ID is declared to be 'sampledashb'.

<?xml version="1.0" encoding="utf-8"?>

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.m-files.com/schemas/appdef.xsd">

  <guid>7BE49057-5EC7-4FC8-9302-32C0BAA3737E</guid>

  <name>Example Dashboard</name>

  <modules>

    <module environment="shellui">

      <file>main.js</file>

      <file>util.js</file>

    </module>

  </modules>

  <dashboards>

    <dashboard id="sampledashb">

      <content>sampledashboard.htm</content>

    </dashboard>

  </dashboards>

</application>

 

At its simplest, the dashboard implementation (sampledashboard.htm) could be something like what is shown below. Note that the dashboard entry point is 'OnNewDashboard', and behaves like the module entry points.

<html>

<head>

<title>Dashboard example</title>

<script type="text/JavaScript">

 

function OnNewDashboard( dashboard )

{  

   // The dashboard code entry point is here.

}

 

</script>

</head>

<body>

The dashboard content goes here.

</body>

</html>

Showing a Dashboard

In order to have the dashboard displayed, the program code must launch the dashboard. Several objects have dashboard launching capability, for example the ShellFrame can show modal dashboard popup dialog. The dashboard can be launched like this:

// Launch the dashboard and wait until the window is closed.

// The shellFrame refers to IShellFrame object.

shellFrame.ShowPopupDashboard( "sampledashb", true, null );

Dashboard Object Model

The dashboard object gets created right after the dashboard appears, and is announced for the dashboard code via OnNewDashboard event handler function. The function receives the dashboard object as a parameter, and is expected to register further event listeners for the dashboard object (e.g., started and stop event listeners). The practice is similar to the module entry functions.

The dashboard object can access the Parent object of the dashboard. The parent is the object which launched the dashboard. Via the parent object, the dashboard implementation can interface with the module that is using the dashboard.

Modal and Modeless Dashboard and the Dashboard Lifetime

A modal dashboard is a dashboard displayed in a popup-window, which prevents user from interacting with any other underlying windows (i.e., a user must close it, before accessing other M-Files UI windows). The lifetime of a modal dashboard is simple to determine; because the user cannot do anything outside of the dashboard, it lasts until the user closes it.

Modal dashboards are launched by using any of the ShowPopupDashboard methods, and by passing a true value for the WaitUntilClosed parameter. The calling module stops and waits until the dashboard is closed.

A modeless dashboard is the opposite of a modal dashboard. It is a popup window that allows the user to interact with the underlying windows. Therefore, it is possible that the object or window that owns the dashboard gets destroyed. Depending on the dashboard settings, the dashboard may automatically close in certain situations.

Modeless dashboards are launched in a similar fashion, using any of the ShowPopupDashboard methods, but passing a false value for the WaitUntilClosed parameter. The calling module keeps going, and the dashboard popup window appears simultaneously. The programmer must acknowledge that the dashboard code is executed asynchronously, and the dashboard object is not available immediately.

By default the dashboard gets closed when the parent object of the dashboard gets destroyed. For example, if the ShellFrame object launched a modeless dashboard, the dashboard is closed when a user navigates to a different view. If the ShellUI object launched the modeless dashboard, the dashboard is persisted between views. However, this behavior can be changed by setting the AutoStopWithParent property of the dashboard object.

The code in a popup dashboard can access the Window object which represents the popup window. The dashboard can also close itself by using the Window::Close method.

Integrated Side Pane or Main Area Dashboard

In a ShellUI module, dashboards can be placed in the preview pane (right pane), or the properties pane (bottom pane). These panes can be accessed via the ShellFrame::RightPane and ShellFrame::BottomPaneproperties. The dashboard can be placed to side pane with ShowDashboard method.

// Launch the dashboard in side pane.

// Here the shellFrame refers to IShellFrame object.

shellFrame.RightPane.ShowDashboard( "sampledashb", null );

 

In addition of the side panes, the dashboard can be displayed over the listing view, to replace the main content area. This can be achieved by calling IShellFrame::ShowDashboard.

The dashboard in integrated child window has some behavioral differences when compared with popup dashboard:

-          Dashboard in side pane cannot set AutoStopWithParent, but it always stops when the parent (the shell pane or shell frame) gets destroyed.

-          Dashboard in integrated child window does not have the own Window object, so the dashboard cannot close its window. However the dashboard can access the parent object (ShellPaneContainer orShellFrame) and change its visibility or content, and effectively close the dashboard.

Transferring Data between the Dashboard and Parent Object

A custom data item can be transferred for dashboard when it is created. The module that displays the dashboard can pass a custom data object as a parameter for the dashboard. The code below launches a popup dashboard window, and passes custom object for it. The custom object contains two static variables (number and string), and single callback method that can be used to communicate back from the dashboard implementation.

// Launch the dashboard and wait until the window is closed.

// Here the shellFrame refers to IShellFrame object.

shellFrame.ShowPopupDashboard( "sampledashb", false,

    {

        mystring: "123",

        mynumber: 13,

        mycallback: function( param ) {

            // Callback implementation

        }

    } );

 

On dashboard side this custom object can be accessed via dashboard object's CustomData property.

{

    // Here the dashboard variable represents the IDashboard object.

    // Use the custom data.

    if( dashboard.CustomData.mystring == "xyz" )

    {

        // ...

    }

 

    // Use the callback of the custom data.

    dashboard.CustomData.mycallback( "abc" );

}