Skip to main content

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, add an AppD entry to public/configs/application/apps.json. Set url to the url of your HTML application.

"apps": [
    ...
    {
        "appId": "MyApp",
        "name": "MyApp",
        "title": "My App's display name",
        "type": "web",
        "details": {
            "url": "https://myapplication",
        },
        "hostManifests" : {
            "Finsemble": {
                "window": {
                    "width": 800,
                    "height": 600
                },
                "foreign": {
                    "components": {
                        "App Launcher": {
                            "launchableByUser": true
                        }
                    }
                }
            }
        }
    },
    ...
]

App configuration​

In Finsemble, you add apps by making entries in the public/config/applications/apps.json file. The entries in this file follow the FDC3 AppD standard. You can find all possible app configurations in the Config reference and a reference for AppD record format in the application directory (appD) tutorial.

Within each AppD entry, you must include an appId, type and details entry that define the identity and launch details for the app. You should also include a hostManifests section with a "Finsemble" element that contains Finsemble specific configuration, deivided into 4 important sub-sections: window, component, and foreign.

  • window - configurations that manage the placement of the app on the screen.
  • component - configurations that affect how Finsemble handles the application.
  • foreign - configurations that other Finsemble modules (such as services or UI components) read when they interact with this app.
  • interop - configurations that affect how Finsemble's extended FDC3 featureset (selectConnect) handles this app.
note

You can override most settings in the window section in calls to FSBL.Clients.LauncherClient.spawn or FSBL.Clients.LauncherClient.showWindow. You'll find these in the Launcher client documentation. The only exceptions are window.affinity and window.options, details of which you'll find in the Config reference.

Find out more about how Finsemble identifies components in the AppIDs and Window Names tutorial.

Logically integrating in-house HTML applications​

A Finsemble app is essentially a webpage running inside a browser window that Finsemble provides. Apps running within Finsemble automatically have access to the Finsemble APIs through global fdc3 and FSBL objects.

note

Apps running outside of Finsemble, called freestanding apps, can import Finsemble's JavaScript adapter to gain access to Finsemble's global API objects.

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

See the API reference for a complete list. The most common API's used include:

FDC3 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.

Authentication - Accept your internal credentials to log into the HTML app.

Integrating third-party HTML applications​

When you want to integrate apps that aren't FDC3-compatible and you don't have access to the source code, all is not lost. You can use a preload to integrate apps without changing their source code. Preloads are scripts that run before an app is loaded, allowing hooks and APIs to be added dynamically.

Adding preloads​

You can add one or more preloads to your HTML app by setting the preload property array in your app's config. You must specify a full path for your preload.

{
    ...
    "hostManifests" : {
        "Finsemble": {
            ...
            "component": {
                "preload": [
                    "https://myurl.com/myfancyscript.js", 
                    "http://myDomain.com/files/file2.js"
                ]
            }
        }
    }
}
note

Your preloads can run before the FSBL or fdc3 global objects are available. To use these objects in a preload use this code:

if (window.FSBL && FSBL.addEventListener) {
    FSBL.addEventListener("onReady", runYourCode);
} else {
    window.addEventListener("FSBLReady", runYourCode);
}
note

You can use the script yarn create-preload <name> to create an empty preload and webpack entries in your seed project. To refer to preloads in your seed project use the $applicationRoot manifest macro plus index.js:

{
    ...
    "hostManifests" : {
        "Finsemble": {
            ...
            "component": {
                "preload": ["$applicationRoot/MyPreload/index.js"]
            }
        }
    }
}

Using cookies with preloads​

Cookies are frequently used in web sessions for authentication. Sometimes a server requires authentication before it will deliver a preload. We recommend using Finsemble's authentication component as a way to establish cookies in preload domains. Finsemble acts just like a browser in that cookies are shared across windows from the same domain. By establishing a web session in the authentication component you can be sure that your cookies are set correctly before Finsemble loads any preloads.

note

You can set a cookie using document.cookie = "username=John Doe";.

Built in preloads​

Finsemble ships with a built in zoom preload. You can load this preload by using the $moduleRoot manifest macro. Here's how:

{
    ...
    "hostManifests" : {
        "Finsemble": {
            ...
            "component": {
                "preload": ["$moduleRoot/preloads/zoom.js"]
            }
        }
    }
}

zoom.js​

zoom.js adds zoom hotkeys and memory into an app. 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​

node_modules/@finsemble/finsemble-core/dist/platform/preloads/nativeOverrides.js is a template that shows you how to overwrite window.open and alert calls with alternatives. In this example, window.open() calls are redirected to FSBL.Clients.LauncherClient.spawn and alert() calls are replaced with a Finsemble notification.

To use these overrides, copy and paste this file into your own project and make the changes you want.

UI considerations​

There are two essential UI considerations to keep in mind when designing an HTML app to work in Finsemble: small form factor and window controls.

Small form factor​

A Finsemble smart desktop consists of many apps running simultaneously on a user's screens. In a smart desktop, users tend to make their apps smaller than they would in a browser. Your apps should look good and be completely functional when running in a small form factor.

note

Be careful about apps that switch into mobile mode when resized (responsive apps). A mobile interface might not be appropriate in a smart desktop. You can use the html.finsemble class to add a specific form factor for smart desktop apps:

html.finsemble mydiv {
   /* */
}

Window controls​

Finsemble handles window management functions, such as maximize, minimize, and components such as a title bar. For this reason, make sure that your HTML apps hides any custom controls when running under Finsemble.

If you have not written a custom title bar then there is no effort required. Finsemble automatically disables the operating system's default title bar.

Using Typescript with Finsemble​

To use Finsemble's global objects in a Typescript file, simply import something from "@finsemble/finsemble-core". If you don't have anything to import then just import *.

import * as Finsemble from "@finsemble/finsemble-core";

fdc3.addContextListener("account", (context) => {
   // do something with the context you receive
});
note

node_modules/@finsemble/finsemble-core/dist/platform/tsconfig-seed.json contains a Typescript config file that the build process references automatically (when running yarn dev in the seed). You can copy this file to your seed project's root and rename it to tsconfig.json if desired or if you need to customize Typescript.

See also​

Reference information about important data for your application can be found in the Component Types and Window Names tutorial.

To integrate native apps, see the Integrating Native Applications tutorial.

Manage memory footprint and performance intelligently by using Process Affinities.

To learn about how to design FDC3 apps, see Integrating FDC3-compliant apps into a workflow using the FDC3 workbench