Integrating HTML applications

Finsemble allows you to assemble different applications into a unified desktop experience. HTML applications can be both visually and logically integrated.

Visual integration allows your application to benefit from Finsemble's UX.
Logical integration allows applications to communicate through Finsemble's API.

This tutorial introduces the concepts needed to integrate HTML applications and webpages into Finsemble workflows.

Visually integrating HTML applications

HTML applications can benefit from visual integration. Visual integration creates form that facilitates function.

Visually integrated windows can participate in a range of UX features. Integrated applications can snap, dock, group, tile, and tab with other Finsemble windows.
Visually integrated applications are spawned and controlled by Finsemble. They gain workspace persistence between sessions, reloading in the same position and with the same content.

To visually integrate an HTML application, simply add it to Finsemble's config. To do this, point the url of the component to the location of your HTML application.

"My Component": {
    "Window": {
        "listName": "My Component",
        "url": "https://yourcomponentlocation",
    }

Component configuration

Finsemble is a configuration-driven platform. As such, you interact with your application components in large part through configuration. An important tool for setting your components' configuration is the Config Reference.

Each component config has three main sections: window, component, and foreign.

window - Configurations that manage the placement of the component on the screen.
component - Configurations specific to this component. Put any custom configurations for your components in this section.
foreign - This section contains configurations that other components and services read when they interact with this component.

Most settings in the window element can be overridden in a LauncherClient.spawn (or showWindow) call. You'll find all those options in the Launcher Client documentation. The only exceptions are window.affinity and window.options, details of which you'll find in the Config Reference.

The component and foreign section configs are expected to be immutable. That is, they never change for a particular component. Again you'll find these defined in the Config Reference.

Finsemble expects each distinct application component to have a unique componentType. The componentType is a key found in the finsemble.components section of the config. By default, this is configured in ../public/configs/application/appd.json. Find out more about how Finsemble identifies components in the Component Types and Window Names tutorial.

As you generate configurations for each component, note that many users simply create a configuration template and tweak a few fields per component (e.g. window.url, component.displayName, etc.). Using this process, each component will be given a unique config chunk.

Logically integrating in-house HTML applications

A Finsemble component is really nothing more than a webpage that runs under the care of an overarching framework. Finsemble components automatically have access to the Finsemble APIs. Your application will have a FSBL object on the global namespace when running in Finsemble. You can check for the existence of the FSBL object to adjust behavior between standalone and framework mode.

This is a rather basic approach, but it can deal with any strict behavioral switches:

if (window.finsemble) {
    // Desktop standalone under Finsemble
} else {
   // Browser
}

Features you can add to your app using the FSBL API

You can use the Finsemble APIs to enable features for your component. How much of each API you use will depend on the use case for your component as well as the needs of the overarching application.

The following features are available from Finsemble:

[Authentication](/docs/7.x/enterprise/authentication/Authentication - Accept your internal credentials to log into the HTML app.

Data Transfer - Allow data to be shared to or from other components using our Drag and Drop Client.

Interop - Give your apps the ability to exchange data on the desktop.

Storage - Give developers the ability to store state for your application on to their own network, giving customers control of their data.

Integrating third-party HTML applications

Because the Finsemble framework is written in HTML5, it's relatively simple to write code that can give HTML applications additional Finsemble capabilities—even if you don't control the source code. This is done by writing code and preloading it into the component's window.

Manually preloading

You can add one or more controlling scripts to your HTML application manually. To do so, you need to add the preload property to the component config. Specify a full path for your preloads. You can specify a list of files to be included.

{
"My Component": {
    "window": {
        "url": "https://someurl.com/foo/bar/"
        ...
    },
    "component": {
        "preload": ["https://myurl.com/myfancyscript.js", "http://yourDomain.com/files/file2.js"]
    }
    ...
}

note

If you don't specify a path for the preload file, Finsemble looks in the ..src/components/mindcontrol/ folder. Make sure your build process puts the file in that folder.

You can also use the CLI to create the files needed for your HTML application component.

Using cookies with preloads

Cookies are frequently used in sessions for authentication. If the preload you want to download requires an authenticated session, you can set a cookie on the session anywhere. A single session is shared across Finsemble. You will be able to create a new window using the preload behind cookie-based authentication. Cookie headers in the session will be applied to preload downloads. You can set a cookie using document.cookie = "username=John Doe";.

Sample preloads

The Finsemble Seed Project ships with a two sample preloads that we use in our UI components: zoom.js and nativeOverrides.js.

zoom.js

zoom.js adds zoom hotkeys and memory into an application. Hit CTRL + and CTRL -, or hold CTRL and use the mouse scroll wheel to zoom in and out. Reload the page or save the component into a workspace, and the zoom is remembered.

Default values for the min and max zoom level, step size, and zoom pop-up timeout can be set via configuration. See the config reference for details.

nativeOverrides.js

nativeOverrides.js is just a file that shows how to overwrite certain native Window functions, such as window.open. Instead of opening a new window, we redirect that function to call LauncherClient.spawn. We also overwrite the alert method to send a notification through Finsemble instead.

UI considerations

There are two core UI considerations when making your HTML application into a Finsemble component: small form factor and window controls.

Small form factor

A Finsemble smart desktop is an amalgamation of several application components running simultaneously. As such, users tend to make their Finsemble components much smaller than standalone applications. Your application components should be functional and aesthetically pleasing when running in a small form factor.

It’s important to avoid having your application component behave like a mobile app when the form factor is reduced. This is a common error when web designers first encounter the complexities involved with running their app on the desktop, and particularly in a small form factor on the desktop. It is vital to prioritize the small desktop format when creating a desktop app.

When running in Finsemble, the class finsemble will automatically be injected into the <html> element. You can use this to drive conditional CSS:

html.finsemble mydiv {
   /* */
}

Window controls

Window management functions, like maximize, minimize, and a title bar, are handled by Finsemble. Your application should cede this control to the framework by checking for the existence of the FSBL object, or by hiding the toolbar based on the existence of the HTML.finsemble class.

If you have not written a custom title bar then there is no effort required here. Finsemble automatically disables the default Windows title bar that your application currently uses.

Using Typescript with Finsemble

Finsemble's seed project comes with a tsconfig.json that is already configured with typescript support. If you are configuring a project from scratch, follow these steps to get typescript support for the FSBL and fdc3 global objects (the Finsemble API):

yarn add @finsemble/finsemble-core
Add a typeRoots section to your tsconfig.json file per the following example (be sure to include node_modules/@types!):

{
    "compilerOptions": {
        ...
        "typeRoots": ["node_modules/@types", "node_modules/@finsemble"]
        ...
    }
}

React apps

To create React application components, generate your React application using your normal methods and create a config entry pointing to the new application's localhost address.

For example:

Use a command prompt and npx to create a new React application:

npx create-react-app my-sample-React-app
cd my-sample-React-app
npm start

Note the localhost address the application is served on.
Create a component config in ../public/configs/application/appd.json and point the url entry to your React app's localhost address:

"My Sample React App": {
    "name": "My sample React app",
    "appId": "My sample React app",
    "description": "A sample AppD entry for a React app component.",
    "manifest": {
        "window": {
            "url": "http://localhost:3000/",
            "width": 400,
            "height": 435,
            "frame": false,
            "resizable": true,
            "autoShow": true,
            "top": "center",
            "left": "center"
        }       
    }   
}

Assuming that "launchableByUser" = true in your config entry, this application component can be launched by the app launcher. The application will automatically reload and update on save (like in a browser).

Alternatively, you can add a React component via the Finsemble CLI.

Angular apps

You can get an Angular app to work with Finsemble with no trouble. We will look at two cases. The first case is if you want your app to run only in Finsemble, and the second case is for apps that can run both in Finsemble and outside of it.

Angular apps running only in Finsemble

Let's first look at an existing Angular app that you want to work only in Finsemble. It doesn't matter if it's build inside Finsemble or built and hosted externally. You configure it the same in both these cases. All that is needed is a config entry that points to your local or hosted app URL.

note

If you don't have an existing Angular app you can create a new one by following the Angular CLI instructions.

Create a component config in ../configs/application/appd.json and point the url entry to your Angular app's localhost address:

"My Sample Angular App": {
    "name": "My sample Angular app",
    "appId": "My sample Angular app",
    "description": "A sample AppD entry for an Angular app component.",
    "manifest": {
        "window": {
            "url": "http://localhost:4200/",
            "width": 400,
            "height": 435,
            "frame": false,
            "resizable": true,
            "autoShow": true,
            "top": "center",
            "left": "center"
        }       
    }   
}

Assuming that "launchableByUser" = true in your config entry, this application component can be launched by the app launcher. The application automatically reloads and updates on save, just like in a browser.

Angular apps running both within and outside of Finsemble

We've just looked at apps that run only within Finsemble. If you want your app to work both inside and outside of Finsemble, you need to do it slightly differently. Here's how:

In the app project folder, run this command (notice that this is a slightly different command than we've seen in the earlier section): yarn add @finsemble/finsemble-core @finsemble/finsemble-electron-adapter
In the app code, add this line, which is the reference path relative to the location of node_modules at the location where you installed finsemble npm modules in the previous step: ///

You're all done. You don't need to add anything to the tsconfig.json file in this case.

Tracking details in HTML apps

You can use the Google tag manager to track details in your app, such as through Google Analytics or Google AdSense.

See these videos in the prescribed order to learn more:

Integrating HTML applications

Visually integrating HTML applications​

Component configuration​

Logically integrating in-house HTML applications​

Features you can add to your app using the FSBL API​

Integrating third-party HTML applications​

Manually preloading​

Using cookies with preloads​

Sample preloads​

zoom.js​

nativeOverrides.js​

UI considerations​

Small form factor​

Window controls​

Using Typescript with Finsemble​

React apps​

Angular apps​

Angular apps running only in Finsemble​

Angular apps running both within and outside of Finsemble​

Tracking details in HTML apps​

See also​