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",
}

The rest of the component's configuration can be found in the Config Reference.

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 if(window.fin) {
    // Desktop standalone under OpenFin
} 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.

OpenFin applications

If you’ve built an application using OpenFin, we have good news: your application is already a Finsemble component! Using Finsemble, you have the ability to further optimize the behavior of your OpenFin application. Don’t worry, you don’t need to fork your code to gain these optimizations—they’re all available from the OpenFin API. You add your OpenFin apps the same way you'd add any HTML application to Finsemble's config: just set the url to the OpenFin manifest's startup_app url (i.e., the root HTML file of the application).

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.


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 the page will zoom in. Reload the page, and the zoom is remembered.

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.


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

Further reading

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

Learn more about the CLI by reading the Finsemble CLI tutorial.