Skip to main content

Application Structure

Each UI Extension Application is a JavaScript application that extends the core functionality of the assocaited M-Files client. Each application can use the UI Extension API to interact with other areas of the UI, and the Vault API to interact with the vault structure and ocntents.

Application Package​

The "Application Package" is a .zip file, e.g. Application.zip, which contains the Application Manifest ()appdef.xml), at least one module file, and all other associated resources such as HTML, CSS, images, or other files needed for the application to run.

Application.zip
├── appdef.xml
├── main.js
├── dashboard.html
└── public
    ├── logo.png
    ├── styles.css
    └── dashboard.js

note

Application Packages typically have a .mfappx extension when distributed to differentiate them from the normal .zip files.

Application Manifest​

The application manifest file - appdef.xml defines common attributes such as the application GUID, its name and version and also ties together the other files which are needed to make the application run. Each application manifest must refer to at least one module, and often also refer to one or more dashboards.

appdef.xml
<?xml version="1.0"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.m-files.com/schemas/appdef-client-v5.xsd">
    <guid>5EA29AF2-1EC9-4AB7-A0D1-FE1D586310D4</guid>
    <name>Name of Application Extension</name>
    <version>0.1</version>
    <description>Description of the App</description>
    <publisher>ACME Corporation</publisher>
    <enabled-by-default>true</enabled-by-default>
    <modules>
        <module environment="shellui">
            <file>main.js</file>
        </module>
    </modules>
</application>

Modules​

The modules define the entrypoint(s) for your application. These are defined by the <module /> element(s) in the application manifest. Each module must specify at least one JavaScript file (<file />) which defines the OnNewShellUI function which will be called when the application starts.

You can learn more about modules from the modules page.

    <!-- inside appdef.xml -->
    <modules>
        <module environment="shellui">
            <file>main.js</file>
        </module>
    </modules>

Dashboards​

Dashboards are HTML pages that are shown within either a custom tab or within a popup dialog. These dashboards are not shown by default, but must be referenced by their dashboard id from within your code.

note

For a complete example see Sample for Popup Dashboard

Each dashboard has a Dashboard id defined in XML like <dashboard id="MySample">. The file that contains the HTML content is defined in the <content> element:

    <dashboards>
        <dashboard id="MySample">
            <content>index.html</content>
        </dashboard>
    </dashboards>

The dashboard id is used by the UI Extensions to open the Dashboard, for example when using ShowPopupDashboard method.

// opens Dashboard with id "MySample"
shellFrame.ShowPopupDashboard('MySample', {})

M-Files Extensibility Protocol Library in Dashboard HTML File​

The HTML file (e.g. index.html, which is mentioned in the application manifest) loads the resources required to show the content of the dashboard. Here, we should include a special script resource called mfiles.extensibility.protocol.js. The actual content of the M-Files Extensibility Protocol library is served from M-Files Server when it loads Dashboard, which ensures that the content is aligned with M-Files Server.

The M-Files Extensibility Protocol library acts as a layer between your application and the M-Files UIX application framework.

dashboard.html
<!doctype html>
<html lang="en">
  <head>
    <title>Sample</title>
    
    <!-- Load M-Files Extensibility Framework library file -->
    <script src="mfiles.extensibility.protocol.js"></script>

    <!-- Load styles and dashboard handler js file -->
    <link href="style.css" rel="stylesheet" />
    <script src="dashboard.js"></script>
  </head>
  <body>
    <div id="content"></div>
  </body>
</html>

Additional Resources​

The Application Package can include images, CSS files or other resources needed by the UI Extension. These may include images, CSS files, or other such supporting content. These files are not referenced within the application manifest, but instead referenced from the dashboard where they are needed:

dashboard.html
<!doctype html>
<html lang="en">
  <head>
    <title>Sample</title>

    <!-- Load M-Files Extensibility Framework library file -->
    <script src="mfiles.extensibility.protocol.js"></script>

    <!--
            Load styles and dashboard handler js file.  These are expected to be in the same directory as the dashboard file
        -->
    <link href="style.css" rel="stylesheet" />
    <script src="dashboard.js"></script>
  </head>
</html>