Finsemble: Understanding UIComponents

Presentation Components

Components are the basic building blocks of the Finsemble application. A component is a piece of HTML5/JavaScript that provides some functionality. Each instance of a component is housed within a Finsemble window, which is a container sitting on top of OpenFin's secure operating layer.

In software development, design principles separate the business logic (the structural element) and the presentation logic (the visual element) of content. This principle can be used to think about Finsemble components as well. Components that deal with raw data and real-world business rules can be called business components. Components that provide chat functionality or deal with charting libraries are examples of business components. By the same token, presentation components are built to provide common UI functionality to end users. A drop-down menu or dialog box would be considered a presentation component. However, all components have the same basic definition and are built using the Finsemble library's client APIs.

The seed project introduces a set of sample presentation components. You can use these samples wholesale or use them as templates for your own components. They can be found in the seed project repo.

These sample presentation components were built using React UI controls. React controls are a library of elements, such as menus and checkboxes, that can be assembled into a single component. Developers can use them to build or modify their own components for Finsemble. The React controls are found in their own repo.

Although the sample components and the controls are production quality, we keep them outside the core because most customers will customize the UI for their own needs. Some of the most important sample presentation components are detailed below.

The Toolbar

Occupying the top portion of every monitor, the toolbar component is the hub of the Finsemble application. Whenever a user wants to launch another component or manage their windows, they use the toolbar. An in-depth discussion on why we made the decisions we made, and how to configure your toolbar, can be found in the toolbar tutorial on GitHub.

The toolbar is spawned by the Workspace service and is available on every monitor. When monitors are added or removed, toolbars are also spawned or removed. Toolbars are workspace independent.

In our sample component, we've included several core features:

  • Launches any component that's pinned to the toolbar
  • Houses user workspaces
  • Provides a menu for users to create new workspaces, save workspaces, or quit the application
  • Provides an app launcher
  • Brings all windows to the foreground with the click of a button
  • Auto-arranges windows

App Launcher

The app launcher is a single window that is spawned by the toolbar in the background. The app launcher is launched from the "Premium" button on the toolbar.

The list of launchable apps is pulled from configs/componentList.json. If components['foreign']['App Launcher'].launchableByUser is true, it will be included in the app launcher.


File Menu

The file menu is a window that's been styled to look like a native Windows file menu. It can be propagated with commands such as quit, restart, etc. The file menu is launched from the Finsemble icon on the toolbar.


Workspace Management Menu

The workspace management menu allows users to create, delete, save, and switch between workspaces. The workspace management menu is launched from the "Workspaces" button on the toolbar.

To learn more about workspaces, check out Understanding Workspaces.


Window Title Bar

The window title bar is a component that's injected into every window. It carries the functionality that users have come to expect from a title bar, such as the ability to close, move, minimize, and maximize, as well as some Finsemble-specific options.

If a component can link to other components, the window title bar carries an icon to open the linker window. If the component can share data using the Drag and Drop Client, the window title bar carries a draggable share icon. When the share icon is dragged from one window to another, data is transferred from the first window into the second.

You can set the title of a window title bar using the Window Client.

FSBL.clients.WindowClient.setWindowTitle(title)

Linker Window

The linker window is a component that interfaces with the Linker Service. It is used to add or remove a Finsemble component from a group, demarcated by color. The linker window is launched from the link icon on the window title bar.

The linker window works like this:

  • The window title bar calls LinkerClient.openLinkerWindow() which sends a router query on the Finsemble.LinkerWindow.Show channel with the window's groups, windowIdentifier and windowBounds.
  • The linker window then updates its display using that information and opens up at the proper position:

      finWindow.showAt(data.windowBounds.left, data.windowBounds.top + 20, function() {});
  • When the user clicks on the group color to update the window's groups, the linker window uses the Linker Client API to update the groups. It then hides itself.

Check out Linking Components for more information about linking and the Linker Service.


Dialogs

Dialogs are a common UI component in both web and desktop applications. Two sample dialogs, the yes/no dialog and single input dialog, are included in the sample component repo. However, it's easy to make your own dialogs for a variety of situations. The Dialog Manager Client simplifies interacting with dialog windows by spawning them and getting data back from them. Reading the API documentation coupled with the Dialog Control documentation will have you well on the way to creating your own dialogs.


Further Reading

These components make use of the following client APIs; reading their documentation will give you additional perspective: