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.
HTML applications can benefit from visual integration. Visual integration creates form that facilitates function.
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",
}
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.
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.
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
}
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.
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.
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.
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";
.
The Finsemble Seed Project ships with a two sample preloads that we use in our UI components: zoom.js and nativeOverrides.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 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.
There are two core UI considerations when making your HTML application into a Finsemble component: small form factor and window controls.
A Finsemble SmartDesktop 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 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.
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:
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 ../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.
If you have an existing Angular application getting it to work with Finsemble is simple. All that is needed is a config entry that points to your locally (or hosted) application URL.
If you don't have an existing Angular application you can create a new one by following the Angular CLI instructions.
url
entry to your Angular
application's localhost address, e.g.:"My Sample Angular App": {
"window": {
"url": "http://localhost:4200/",
"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).
To get full typescript support for the FSBL object (Finsemble) in Angular components you will need to do the following:
yarn add @finsemble/finsemble-core @finsemble/finsemble-electron-adapter
import '@finsemble/finsemble-core'
at the top of
your file."node_modules/@finsemble/finsemble-core/types"
it should look something like this if you use the Angular CLI:{
"extends": "./tsconfig.json",
"compilerOptions": {
"outDir": "./out-tsc/spec",
"types": ["jasmine", "node_modules/@finsemble/finsemble-core/types"]
},
"files": ["src/test.ts", "src/polyfills.ts"],
"include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
}
Typescript will now work as expected with Finsemble in your project!
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.