UI Components

UI components provide common functionality to end users, e.g., drop-down menus or dialog boxes. In Finsemble, these features are just HTML5 windows given functionality that simulates their desktop equivalents.

The seed project provides a set of sample UI 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 UI components are production quality, their inclusion in your application is optional.

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

The Toolbar

Toolbar on GitHub

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

- Toolbar config

The toolbar's config is found at ../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": "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,
    "maxHeight": 39,
    "minHeight": 39,
    "minWidth": 300,
    "canGroup": false,
    "options": {
        "autoShow": false,
        "contextMenu": false,
        "showTaskbarIcon": false,
        "smallWindow": true
    }
},

App Catalog (Finsemble Flow)

App catalog on GitHub

The app catalog is a UI component designed to manage a large application library. Use the app catalog to provide your end users with access to the applications they need to do their work. End users use the app catalog to add applications to their advanced app launcher.

The app catalog aids in discoverability and searchability, making it easy for end users to select the apps that are most relevant to their work. Applications are displayed in carousels so that users can see what is available to them. Users can also search or filter apps by tags.

Note: At this time, the app catalog is designed to work with HTML applications only. The app catalog does not support native applications.

FDC3 App Directory

The app catalog is supplied information from a RESTful API server that you build. The app catalog is designed to read data adhering to the FDC3 specification.

FDC3 is an emerging taxonomy for interoperability shared by several leading financial institutions. The FDC3 App Directory provides a secure identity for application hubs. Read more about FDC3 App Directories for more information about this specification. The app catalog supports FDC3 version 1.0.0.

As an example, we've supplied a lightweight implementation of an FDC3 App Directory. We use this for testing the app catalog, and supply it as a starting point for your own efforts. Please see Finsemble's FDC3 Application Directory Web Service repo here.

The FDC3 application specification defines how you will present application data to your end users. However, there are a few Finsemble-specific fields that are important for the app catalog. These are defined in this example:

{
        "name": "Welcome Component", // String. The name of your component to be displayed in the app catalog.
        "type": "component", // At the moment, the only value supported for the type field is "component." In the future, this field might allow for a broader range of data to be displayed and delivered via the app catalog.
        "entitled": true, // Boolean. If true, the end users can add the application to the advanced app launcher. If false, they cannot access the application.
        "description": "This is the component that welcomes you to Finsemble. It also links you to the documentation. We encourage all users to read our documentation.", // String. This is the description of the component displayed to the end users .
        "appId": "welcome-comp", // String. The unique identifier for a specific application instance.
        "manifest": "{\"window\":{\"url\":\"http://localhost:3375/components/welcome/welcome.html\",\"affinity\":\"workspaceComponents\",\"frame\":false,\"resizable\":true,\"autoShow\":true,\"top\":\"center\",\"left\":\"center\",\"width\":400,\"height\":432},\"component\":{\"displayName\":\"Welcome Component\",\"spawnOnStartup\":false,\"preload\":\"http://localhost:3375/preloads/zoom.js\"},\"foreign\":{\"services\":{\"windowService\":{\"allowSnapping\":true,\"canGroup\":true,\"allowAutoArrange\":true,\"allowMinimize\":true}},\"components\":{\"App Launcher\":{\"launchableByUser\":true},\"Window Manager\":{\"showLinker\":true,\"FSBLHeader\":true,\"persistWindowState\":true,\"title\":\"Welcome to Finsemble\"},\"Toolbar\":{\"iconClass\":\"ff-component\"}}}}", // String. This must be the stringified object of the config supplied in components.json.
        "manifestType": "Finsemble", // String. Currently, only "Finsemble" type is supported, but future implementations might include additional types as the FDC3 standard becomes more prevalent.
        "version": "3.0.1", // String. Version of the application.
        "releaseNotes": "This is the only version of the Welcome Component.", // The app catalog shows release notes to any user viewing a specific app. This is the field to supply those notes. i.e., "Fixed a bug where Welcome Component wasn't maxmizing correctly."
        "tooltip": "Welcome component", // String. The tooltip description.
        "images": [ // Array of objects. An array of images displayed to the user in the app catalog carousel.
            {
                "url": "https://i.imgur.com/7T4Zeqi.png", // The location of the image for the carousel.
                "tooltip": "Welcome Component" // The hover tooltip displayed when hovering over the image in the carousel.
            }
        ],
        "tags": [ // Array of strings. An array of tags attached to the application; searchable by the end user.
            "Welcome",
            "App",
            "Documentation"
        ],
        "contactEmail": "info@chartiq.com", // String. Email set to receive inquiries about the application.
        "supportEmail": "finsemble@chartiq.com", // String. Email set to field support questions about the application.
        "publisher": "ChartIQ", // String. The name of the company that owns the application.
        "icons": [ // Array of objects. An array of the icons used for the application. The 0th icon listed in the array will be treated as the app's main icon and displayed in an "app card."
            {
                "url": "https://i.imgur.com/DCljkMy.png", // The location of the image for the icon.
            }
        ],
        "url": "$applicationRoot/components/welcome/welcome.html" // The URL location of the application.
    }

Note: The app catalog makes use the App Directory specification with some proprietary changes. These changes are as follows:

  • Currently, all of the fields in the application spec are required.
  • On first load, the app catalog grabs all apps from the /v1/apps endpoint.
  • All the apps are loaded into memory when initially pulled from the server, whereas the FDC3 app specification defines an endpoint to receive information about a single app (by appId) via POST and add it to, or update it within, the set of available components. When the catalog loads an app's showcase page, the information is retrieved from memory and no updates or additions are currently supported via calls to /v1/apps/{appId}.
  • The FDC3 spec does not define a set of parameters for using the /v1/apps/search endpoint. Our implementation sends the search text and any selected tags. The /v1/apps/search endpoint is responsible for returning filtered information based on those parameters which the catalog displays.
  • The FDC3 spec also does not define an endpoint for fetching available tags. Our implementation expects an endpoint (/v1/tags/) that should return an array of all possible application tags.

App Launcher

App launcher on GitHub

The app launcher lists all of your Finsemble components. It's launched from the "Apps" button on the toolbar.

The list of launchable apps is pulled from configs/components.json. If components['foreign']['App Launcher'].launchableByUser is true, it will be included in the app launcher. The app launcher filters components based on a "mode" property in the component's config.


Advanced App Launcher (Finsemble Flow)

Advanced app launcher on GitHub

The advanced app launcher is available through Finsemble Flow. In contrast to app launcher's dropdown menu, the advanced app launcher is a pop-out menu. It comes with search capabilities and the ability for end users to organize their application components into folders. ChartIQ supports up to 200 application components in the advanced app launcher menu. It is launched from the "Apps" button on the toolbar.

There are two methods to add application components to the advanced app launcher:

  • You can add application components through configuration using configs/components.json. If components['foreign']['App Launcher'].launchableByUser is true, it will be included in the app launcher.
  • The end user will add application components using the app catalog's UI.

Note: It is possible that these two methods might interact in unexpected ways. If an end user adds an application component that was already added through configuration, the advanced app lauancher will contain a duplicate entry. If an end user opts to remove one of these duplicate apps from their advanced app launcher, both apps will be removed. (Of course, the end user may use the app catalog to add this app back later.) This is a known issue that will be resolved in a forthcoming release.


Authentication Login Window (Finsemble Connect)

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 (Finsemble Flow)

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 (Finsemble Connect). 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/workspaces.json. Delete the welcome component from the list of components.


Window Title Bar (aka the FSBLHeader)

Windows title bar on GitHub

The window title bar is a component that's injected into every window as long as the config FSBLHeader is set to true or an object with parameters, as per the Window Client.

This component 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.


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   UI components provide common UX functionality to end users. Each UI component is just a HTML5 window styled to look like a common UX feature.
 

Further reading

  • White labeling is made very simple in Finsemble. To learn more, check out the White Labeling tutorial.
  • These sample UI 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 UI Components tutorial.