Presentation Components

Design principles separate the business logic (the structural element) and the presentation logic (the visual element) of content. We use this principle to talk about Finsemble components. 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. These features are just HTML5 windows given functionality that simulates their desktop equivalents.

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

The toolbar component is the hub of the Finsemble application. 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. Toolbars are workspace independent.

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

  • Launches any component or workspace that's pinned to the toolbar
  • Provides a menu for users to create new workspaces, save workspaces, or quit the application
  • Provides an app launcher
  • Hosts the auto-arrange, bring-to-front, and minimize-all buttons

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/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/toolbar/toolbar.html",
    "width": 600,
    "height": 39,
    "dockedHeight": 39,
    "top": 0,
    "left": 0,
    "right": 0,
    "position": "available",
    "autoShow": true,
    "dockable": [
        "top",
        "bottom"
    ],
    "maxHeight": 39,
    "minHeight": 39,
    "minWidth": 300,
    "docked": "top",
    "canGroup": false,
    "options": {
        "autoShow": false,
        "contextMenu": false,
        "showTaskbarIcon": false,
        "smallWindow": true
    }
},

- Floating vs Docked

The Finsemble toolbar has two modes: docked to a monitor, and free floating. The free floating toolbar will not snap to any other components. Other components will not snap to it. If moved into the top or bottom of a monitor, it can dock to the monitor, reducing the size of the monitor that it's on and preventing other components from moving into that space.

The default toolbar config allows for this functionality (see above). To make the toolbar fixed, simply remove the dockable and docked properties.


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 Login Window

Authentication login 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.
  • Option to select which (if any) monitors the toolbar will spawn on. NOTE: This will only work with Finsemble versions < 3.1 as the dockable toolbar cannot be on multiple monitors

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 hosts the standard functionality of a window title bar (close, maximize, minimize), but also hosts several Finsemble-specific options, including Finsemble's data sharing capabilities and window grouping functions.

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.


check   Presentation components provide common UI functionality to end users. Each presentation component is just a HTML5 window styled to look like a common UI feature.
 


Further reading

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

  • White labeling is made very simple in Finsemble. To learn more, check out the White Labeling tutorial.