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 ../configs/application/components.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.

Quick components

Even a Finsemble end user can visually integrate HTML applications or web pages. By clicking on the "Apps" menu button and selecting "Create New Component," an input is launched that allows an end user to load a URL into a component window. This quick component is just a webpage that benefits from Finsemble's visual integration features.


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.FSBL)) {
    // 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 - 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.

Linking - Give users the ability to synchronize the context of your app with other components, e.g., synchronize by stock symbol, using our Linker Client.

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.


React applications

It is simple to create React application components. Simply generate your React application using your normal methods and create a config entry pointing to the new application's localhost address.

For example:

  1. 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
  1. Note the localhost address the application is served on.

  2. Create a component config in ../configs/application/components.json and point the url entry to your React application's localhost address, e.g.:

"My Sample React App": {
            "window": {
                "url": "http://localhost:3000/",
                "frame": false,
                "resizable": true,
                "autoShow": true,
                "top": "center",
                "left": "center",
                "width": 400,
                "height": 432
            }

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.


check   Because the Finsemble framework is written in HTML5, integration of HTML applications and webpages is a simple process.
 

Further reading

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

To integrate your binary apps, read the Integrating Native Applications tutorial.

Manage memory footprint and performance intelligently by using Process Affinities.