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. It's worth remembering that features like the toolbar or dropdown menus are just HTML5 windows operating with desktop application-like functionality.

The seed project provides 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. Though these presentation components are production quality, their inclusion in your application is optional.

Some of the most important sample presentation components are detailed below.

The Toolbar

Toolbar on GitHub

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. 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. The toolbar is sensitive to which monitor the user accesses it from; if you launch a component from the toolbar on your left monitor, the component will spawn on the left monitor. 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

The toolbar supports a "right", "center", and "left"section and those are created based on the align property of the items on the toolbar. However, please note that the "center" section is reserved for toolbar pins (see below), so by default, this section is not available. It then creates buttons for each config (see below for a sample config) item in the menuItems based on the type property. The currently created types are:

  • menu - This will create a MenuLauncher FinsembleButton to launch menus. When the toolbar loads, it pre-spawns all menu components in a hidden state to improve performance.
  • component - This will create a AppLauncher FinsembleButton to spawn a Finsemble component.
  • separator - This will create a separator.
  • reactComponent - This is used to insert custom React controls into the toolbar.

It also uses a customized Finsemble button as the overflowMenuControl for the "center" section of the Finsemble toolbar section.

Another customized Finsemble button, the "Workspace Launcher Button," provides a way to switch to a specific workspace. The click event for the button dispatches a message to the Workspace Management Menu for switching workspaces.

- Toolbar store

The toolbar component creates a global store using the Finsemble Distributed Store Client called Finsemble-Toolbar-Store. The toolbar initially loads the items from the config into the menus field of the store. Updating the menus field will update the items on the toolbar.

- Toolbar pins

The toolbar also provides the functionality to "pin" items to the toolbar in the "center" section. For this functionality, the components that need to pin items to the toolbar need to add a pin to the pins field of the Finsemble-Toolbar-Store. The pins are configured in the same way as the items in the menuItems. For sample code, see the app launcher and the workspace management menu which make use of this functionality. Pinned items can be moved around the toolbar by way of drag and drop.

The toolbar saves pins to storage using the Finsemble Storage Client and loads them back from storage on startup.

- Adding custom React controls to the toolbar

The Finsemble toolbar component demonstrates how to add custom React components into the toolbar using the "AutoArrange" and "BringToFront" components. To add your custom components, add them to the customComponents array in toolbar.jsx:

import MyCustomReactComponent from 'MyCustomReactComponent';
customComponents['MyCustomReactComponent'] = MyCustomReactComponent;

- Toolbar config

The toolbar's config is found at finsemble-seed/src/components/toolbar/config.json. If this file is blank, Finsemble will read from the finsemble.menus section of the config. The type determines what component is used to render that item on the toolbar. We have sample components for launching menus, components, switching workspaces and a reactComponent type for use with any custom React component.

[
    {
        "align": "left",
        "iconClasses": "finsemble-toolbar-brand-logo",
        "icon": "http://localhost:3375/components/assets/img/Finsemble_Taskbar_Icon.png",
        "menuType": "File Menu"
    },
    {
        "align": "left",
        "type": "reactComponent",
        "reactComponent": "Search"
    },
    {
        "align": "left",
        "label": "Workspaces",
        "menuType": "Workspace Management Menu",
        "reactComponent": "WorkspaceMenuOpener",
        "type": "reactComponent"
    },
    {
        "align": "right",
        "type": "reactComponent",
        "reactComponent": "AutoArrange"
    },
    {
        "align": "right",
        "type": "reactComponent",
        "reactComponent": "MinimizeAll"
    },
    {
        "align": "right",
        "type": "reactComponent",
        "reactComponent": "BringToFront"
    },
    {
        "align": "left",
        "label": "Apps",
        "menuType": "App Launcher"
    }
]

Here is a sample config to use with our sample toolbar. For more details on the Finsemble config, see our Configuration tutorial.

"window": {
    "id": "launcher",
    "url": "$applicationRoot/components/system/toolbar/toolbar.html",
    "height": 40,
    "top": 0,
    "left": 0,
    "right": 0,
    "position": "available",
    "claimMonitorSpace": true, // This tells Finsemble not to remove the space occupied by the toolbar from the available space on the monitor.
    "addToWorkspace": false, // Toolbars are not part of the workspace.
    "options": {
        "contextMenu": false,
        "resizable": false,
        "showTaskbarIcon": false,
        "resizeRegion": {
            "bottomRightCorner": 0,
            "size": 0
        }
    }
},

App Catalog

App catalog on GitHub

The app catalog lists all of your Finsemble components. It's launched from the "Apps" button on the toolbar. The app catalog contains any component that is launchableByUser. It filters components based on a "mode" property in the component's config.


App Launcher

App launcher on GitHub

The app launcher acts like a dropdown menu spawned spawned by the toolbar. The app launcher is launched from the "Apps" 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.


Authentication Log-in Window

Authentication log-in window on GitHub

A sample authentication example is built into the Finsemble seed project. To enable this sample code in the Finsemble seed project (or your own project), set isAuthEnabled to true in configs/application/config.json. Once authentication is enabled, users will be prompted for a username and password via the authentication log-in window when the application starts.

Note: With the sample authentication, users can enter any password since it isn't verified.

Setting up authentication for your own project can be done by consulting the Authentication tutorial.


Dialogs

Dialogs are a common UI component in both web and desktop applications. Three sample dialogs, the yes/no dialog, input and selection 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.


File Menu

File menu on GitHub

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.


Linker Window

Linker window on GitHub

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

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


Search Menu

Search menu on GitHub

The search menu populates with results from the Search Client. By default, Finsemble comes prepackaged with two search providers: Installed Components and Installed Workspaces. The search menu is launched from the magnifying glass button on the toolbar.

More information about Finsemble's search functionality can be found in the Search tutorial.


User Preferences Window

User preferences window on GitHub

User preferences are developer-defined options that give users the ability to fine-tune their Finsemble experience. The end user can only modify what you give them access to. Our seed project allows users to customize the following:

  • Import and export workspace templates. This allows users to create and share the configurations that are most effective for their workflows and share them.
  • Rename workspaces.
  • Create new workspaces based on a template.
  • Specify which workspace will load on start-up.

You can read more about user preferences in the Configuration tutorial.


Welcome Component

Welcome component on GitHub

The welcome component is simply a window that contains a link to this documentation. It's intended to display to a new user that they have successfully installed and started Finsemble.

The welcome component is included as part of the default workspace in the seed project. If you wish to no longer see the welcome component by default, simply modify finsemble-seed/config/other/defaultWorkspace.json. Delete the welcome component from the list of components (lines 7-14).


Window Title Bar

Windows title bar on GitHub

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)

Workspace Management Menu

Workspace management menu on GitHub

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, you can read Understanding Workspaces.


Robust customizability via React UI controls

These sample presentation components were built using React controls. Developers can use the React controls to build or modify their own components for Finsemble. To find out more about the React controls, see the Modifying Presentation Components tutorial.


Further reading

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