Skip to main content

Customizing UI

The easiest way to customize Finsemble UI is to use the Smart Desktop Designer (SDD). You can achieve quite a lot of customizations this way. You can design a theme, specify icons, and also create and organize menus. For more info, see Theme and Toolbar.

The two most important UI components are:

  • The Toolbar, the dockable strip that manages the smart desktop. The Toolbar component includes menus for launching apps and workspaces, pinned favorites and various button controls.

  • The WindowTitleBar, the strip that appears on top of windows. The WindowTitleBar component lets users move, maximize, minimize, and tab windows.

SDD is powerful and allows you to customize a lot of features. But there are some more advanced features that you can't customize with SDD. For those, Finsemble includes a set of ready-made components to tweak your smart desktop. We call them "UI components". Each one runs as an independent window running its own code.

Outside of SDD, there are two ways to customize UI components:

  • By modifying their React-based TSX templates.
  • By modifying the CSS theme applied to the smart desktop.

This guide will cover both methods, giving examples along the way.

Modifying templates​

You can replace Finsemble's built-in UI components with custom components that are built using our React UI API. The starting point for each component is a .tsx template that you can install by using a CLI command:

yarn template Toolbar

This command does three things:

  1. Creates a file src/Toolbar/index.tsx in your seed project. This is Finsemble's default template for the Toolbar component.
  2. Creates a file webpack/entries.json that contains a reference to the template. Finsemble's build system uses this entry.
  3. Adds a 'component' entry to public/configs/application/config.json. This entry points to $applicationRoot/Toolbar/index.html. The index.html file is generated later, when you compile the template. This config is how Finsemble determines to use your component instead of its built-in version.

After you add a template, you must run Finsemble's build system to compile it. Run yarn dev in a terminal window to compile and then launch Finsemble. You need to stop and restart Finsemble to see changes to the UI components.

See Finsemble's build process for more details about build options.

note

Run yarn template without specifying any UI component to get a list of all the available templates.

Templates import modules from the Finsemble UI API, a React library providing ready-made, Finsemble-themed components. The UI API also provides a React Hook-based API for communicating with the rest of the Finsemble system. You don't need to know React Hooks to use the Finsemble UI API, but you can read about them in the article Introducing hooks.

In the following examples we customize the Toolbar. You can use these same techniques to customize other UI components, such as the WindowTitleBar.

Example: Customizing the Toolbar component​

In this example, we work within the Finsemble seed project. Clone it from Github before you begin.

Run yarn template Toolbar to install the template. Verify that src/Toolbar/index.tsx had been created.

Disabling a toolbar​

Here is a simple trick to disable the toolbar in your Finsemble app. Add a custom toolbar (by running the command yarn template Toolbar). Then add this code to src/Toolbar/index.tsx:

FSBL.Clients.WindowClient.getCurrentWindow().hide();

Removing a button​

Suppose you want to remove the button that minimizes all windows. Just delete the MinimizeAll React component from this file. It's that simple!

Adding a button​

Adding buttons is also a common task. Suppose you'd like to add a button that launches Google. Our templates are just plain ol' React in tsx files, so you can add the following code directly to Toolbar.tsx or import it from a separate file.

First we'll create a function that launches Google via the Finsemble Client API. Finsemble makes the FSBL object automatically available in the global scope via preloading, so there's no need to import it.

const launchGoogle = () => {
    FSBL.Clients.LauncherClient.spawn("", { url: "https://www.google.com/" });
};

Next create a React component for your button that calls launchGoogle() on click. You may style it however you like, or use Finsemble's built-in classes to match the existing buttons.

const LaunchGoogle = () => {
    return (
        <div className="finsemble-toolbar-button" onClick={launchGoogle}>
            G
        </div>
    );
};

Now place your new button in the existing JSX markup. We'll put it into the right hand section of our toolbar, but of course you can put it anywhere. You can reorganize the toolbar in any way that you wish simply by rearranging the template.

<ToolbarSection className="right">
    <div className="divider"></div>
    <AutoArrange />
    <LaunchGoogle />
    <MinimizeAll />
    <RevealAll />
</ToolbarSection>

Build and launch your project to try out the new button by running yarn dev.

Remember, you have access to the entire Finsemble API, HTML5, and the React ecosystem to build cool stuff!

Changing the look or contents of a button​

Every Finsemble React component accepts props.children as an override. This allows you to change the look of UI elements without having to rewrite them. In this example, we replace the icon for the <MinimizeAll> component with a div that contains the letter "M". Clicking the button will still minimize all windows but you can make it look any way that you wish simply by changing the markup.

<ToolbarSection className="right">
    <div className="divider"></div>
    <MinimizeAll>
        <div>M</div>
    </MinimizeAll>
    <RevealAll />
</ToolbarSection>

Adding a toolbar menu​

One of the popular customizations is adding toolbar menus. There are 2 ways to do this. The first one is by using the Toolbar page of the Smart Desktop Designer (SDD). This option is great if you want to add a toolbar menu at the design stage.

You can also configure your new menu programmatically. All you need is to add an entry in the toolbarMenus section of your config file. Specify the name of your menu so users know what the menu is for, and then list all the apps you want to appear on your menu in the same order you want them to appear for the user. Use the position parameter to specify the order of multiple menus. The higher the number, the more to the right the menu will be placed on the toolbar. Here is an example:

"toolbarMenus": {
    "ID": {
        "displayName": "myMenu",
        "applications": [
            "App1",
            "App2"
        ],
        "position": 0
    }
},

Changing the theme​

Your smart desktop's theme is controlled by the assets/css/theme.css file in the Finsemble seed project. By adding directives to this file, you can globally control your SmartDesktop's look and feel.

note

theme.css is loaded by UI components at runtime. You could directly import this file in your index.tsx file but it's not necessary.

You can add your own css directives to theme.css, or you can import your own .css files. Finsemble's build system includes support for loading CSS files using Webpack's style-loader.

The smart desktop's look and feel is primarily driven by the CSS variables that make up the global theme, but there are also other component-specific variables. You can look in node_modules/@finsemble/finsemble-core/dist/platform/assets/css to see all of Finsemble's CSS files.

You can also include Finsemble's theme in static HTML files by using the @import directive. Mke sure that the relative path is correct as deployed.

@import url("../../../assets/css/theme.css");
note

Typically you don't need to restart Finsemble after making a CSS modification. Just reload a UI component by focusing its window and clicking ctrl+r.

To get the hang of things, let's work through a few examples, each using a different method.

Example 1: Theme CSS variables​

As noted, most aspects of the smart desktop's look and feel are driven by the theme. For example, the toolbar's background color is driven by the "core-primary" CSS variable. Add the following line to theme.css to turn the Toolbar red (press ctrl+r when focused on it to reload):

--core-primary: "red";

Example 2: Component CSS variables​

The "core-primary" variable from the above example is used by many components. Thus, changing this single variable will affect your entire application. Usually this is what you want; however, if you need fine-tuning, there are additional, component-specific CSS variables you can customize.

For instance, you can add the following line to theme.css to change the background color of only the toolbar to a nice chartreuse:

:root {
    /* ... */
    --toolbar-background-color: #75760e;
    /* ... */
}

CSS is more art than science. If you have a question about a variable or directive, email support!

Example 3: Customize by overriding CSS directives​

Finally, for very fine tuning, you may add CSS directives to override any of Finsemble's built in CSS. For instance, to take away the text shadow inside the Toolbar you can directly override that style by adding the following at the top level:

.finsemble-toolbar {
    text-shadow: none;
}

To accomplish that deeper level of customization just find the right classes using Chrome's debugger or reach out to us and we can tell you exactly which CSS directive to set!

note

Finsemble is styled for dark backgrounds. If you want to implement a color palette that has light backgrounds you will likely have to also change the font colors for legibility. You can also change typography settings such as size, weight, and font-family.

Font Finance​

Finsemble's default look and feel uses an icon library Font Finance (inspired by Font Awesome). font-finance is included with Finsemble and you can import it into any component that you build.

Importing font-finance into a React component:

import "@finsemble/finsemble-core/dist/platform/assets/css/font-finance.css;

You can then use font-finance to create icons by setting the applicable class. This example creates a chart-advanced icon:

<div class="icon ff-chart-advanced"></div>

See also​

Toolbar

For a list of all Finsemble's UI components and how to customize them, see the Component catalog.