Embedding Shell Listings and File Previewers in Dashboards

Dashboards are UI Extensibility Framework components that are used to provide the user interface for extensibility applications. Dashboards run on browser control that can host ActiveX controls as a part of the user interface. M-Files provides some built-in ActiveX controls that can be used to customize the M-Files look and feel.

ActiveX controls are created in HTML code with <object> tag, with classid attribute set to component's CLSID. Because each M-Files version has different CLSID for its components, a fixed CLSID must not be used, but the component's CLSID must be referred as a named constant. Therefore the HTML code for ActiveX controls usually needs to be constructed dynamically.

Currently available built-in ActiveX controls and their class ID constants:

Shell Listing: MFiles.CLSID.ShellListingCtrl
File previewer: MFiles.CLSID.PreviewerCtrl

Embedding Additional Listings

In addition to the normal shell listing, additional listing object can be created and displayed on dashboards. The ActiveX control implements the AttachToListingWindow method, that is used to attach the ActiveX control with the listing object. The listing (content) object to attach can be created with CreateAdditionalListingForPath Method or CreateAdditionalListingForView Method.

The ShellListingCtrl.AttachToListingWindow method	Copy Code
void AttachToListingWindow( [ in ] IUnknown* shellListing );

The code below illustrates how to create the ShellListingCtrl ActiveX object dynamically in HTML code. It utilizes jQuery library for HTML DOM modifications.

Creating ShellListingCtrl object dynamically HTML	Copy Code
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title></title> <meta http-equiv="content-type" content="text/html;charset=UTF-8"> <!-- Include the jQuery Core library --> <script type="text/javascript" src="jquery-ui-1.10.0.custom/js/jquery-1.9.0.js"></script> <!-- Dashboard implementation --> <script type="text/javascript"> "use strict"; /** * Gets called when a new dashboard object is created. * * @param { dashboard } The newly created dashboard. / function OnNewDashboard( dashboard ) { // Register a handler to listen to the started event. dashboard.Events.Register( MFiles.Event.Started, getDashboardStartedHandler( dashboard ) ); } /* * Returns the event handler to handle the "started" event of a dashboard. * * @param { dashboard } The current dashboard object. */ function getDashboardStartedHandler( dashboard ) { // Return the event handler. return function() { // Create new listing object. The shell frame was passed as a custom data. var shellFrame = dashboard.CustomData; var listing = shellFrame.CreateAdditionalListingForPath( "Checked Out to Me\\" ); // Add the ActiveX control to the DOM. $( "#mf-listing" ).html( "<object classid='clsid:" + MFiles.CLSID.ShellListingCtrl + "' style='width: 400px; height: 300px;'> </object>" ); var docListCtrl = $( "#mf-listing object" ).get( 0 ); // Attach the listing to the ActiveX control. docListCtrl.AttachToListingWindow( listing ); }; } </script> </head> <!-- The dashboard content --> <body> Checked out to me: <div id="mf-listing"></div> </body> </html>

Creating ShellListingCtrl object dynamically HTML

Copy Code

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title></title>
<meta http-equiv="content-type" content="text/html;charset=UTF-8">

<script type="text/javascript" src="jquery-ui-1.10.0.custom/js/jquery-1.9.0.js"></script>

<script type="text/javascript">

"use strict";

  /**
   * Gets called when a new dashboard object is created.
   *
   * @param { dashboard } The newly created dashboard.
   */
  function OnNewDashboard( dashboard ) {

   // Register a handler to listen to the started event.
   dashboard.Events.Register( MFiles.Event.Started, getDashboardStartedHandler( dashboard ) );
  }

  /**
   * Returns the event handler to handle the "started" event of a dashboard.
   *
   * @param { dashboard } The current dashboard object.
   */
  function getDashboardStartedHandler( dashboard ) {

// Return the event handler.
return function() {

    // Create new listing object. The shell frame was passed as a custom data.
    var shellFrame = dashboard.CustomData;
    var listing = shellFrame.CreateAdditionalListingForPath( "Checked Out to Me\\" );

    // Add the ActiveX control to the DOM.
    $( "#mf-listing" ).html( "<object classid='clsid:" + MFiles.CLSID.ShellListingCtrl + "' style='width: 400px; height: 300px;'> </object>" );
    var docListCtrl = $( "#mf-listing object" ).get( 0 );

    // Attach the listing to the ActiveX control.
    docListCtrl.AttachToListingWindow( listing );
   };
  }

</script>

</head>

<body>
Checked out to me:
<div id="mf-listing"></div>
</body>
</html>

Embedding File Previewers

File previewer ActiveX component can display file content previews for any supported file format for files in M-Files or on local disk. It should be created dynamically by using MFiles.CLSID.PreviewerCtrl as class ID, in similar manner like the ShellListCtrl is created above.

The PreviewCtrl ActiveX object exposes following methods:

Example Title	Copy Code
HRESULT ShowFilePreview( [ in ] BSTR bstrFilenameWithAbsolutePath ); HRESULT ClearPreview();