Finsemble includes a set of ready-made components to build your SmartDesktop. We call these "UI Components". Each one runs as an independent window running its own code.
The two most important UI Components are:
The Toolbar, the dockable strip that manages the SmartDesktop. The toolbar includes menus for launching apps and workspaces, pinned favorites and various button controls.
The Window Titlebar, the strip that appears on top of windows. The window titlebar lets users move, maximize, minimize, and tab windows.
There are two ways to customize UI Components:
This guide will cover both methods, giving examples along the way.
Each UI Component is represented as a single React component in the
src/components folder of the seed project. In
turn, these top-level components are built 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 (familiarity with React Hooks isn't necessary to use the Finsemble UI API, but the curious can read
about them here).
In the following examples we'll customize the Toolbar. These same techniques can be used to customize other UI Components such as the Window Titlebar.
We'll work within the Finsemble Seed project. Make sure you've cloned it from Github.
First, find the Toolbar's template file in the following directory:
src/components/toolbar/src/Toolbar.tsx
(Here it is on Github)
Let's get to work customizing our Toolbar!
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 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. Remember, you have access to the entire Finsemble API, HTML5, and the React ecosystem to build cool stuff!
Every Finsemble React UI Component accepts props.children as an override. This allows you to change the look of UI
elements without having to rewrite them. In the following 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>
Your SmartDesktop's theme is controlled by the ./assets/css/theme.css file in the Finsemble seed project. By adding directives to the this file, you can globally control the SmartDesktop's look and feel.
The seed project uses Webpack to bundle CSS modules along with JS files, so including CSS in a UI Component is as easy importing it. Here's a snippet taken from Toolbar.tsx:
src/components/toolbar/src/Toolbar.tsx
// finsemble.css contains all of the styles used within the Finsemble React UI library
import "@finsemble/finsemble-ui/react/assets/css/finsemble.css";
// theme.css is imported afterwards, allowing you to override CSS and to set theme variables
import "../../../../assets/css/theme.css";
You'll find similar code in the tsx for all of Finsemble's built in UI components. You should follow this pattern for any React-based components that you create.
The SmartDesktop's look and feel is primarily driven by the CSS variables that make up the global theme, but other
component-specific variables exist, all of which are included in the global stylesheet, finsemble.css. After building
the seed project, you can look in dist/assets/css/finsemble.css to see all of Finsemble's CSS variables, any of which
may be overridden.
Finsemble's theme can also be included in static HTML files. Here's an example from the Welcome Component, which is a static webpage.
src/components/welcome/welcome.css
@import url("../../../assets/css/finsemble.css");
@import url("../../../assets/css/theme.css");
body {
...
Finsemble's Seed project "watches" CSS. It isn't typically necessary to restart Finsemble after making a CSS
modification. Simply reload your components by focusing their windows and clicking ctrl+r.
To get the hang of things, let's work through a few examples, each using a different method.
As noted, most aspects of the SmartDesktop'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";
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;
/* ... */
}
You can find this variable, and others like it, in dist/assets/css/finsemble.css. CSS is more art than science - if
you have a question about a variable or directive, drop us an email!
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!
🌘 Finsemble is styled for dark backgrounds. Implementing a color palette containing light backgrounds will likely require that you also change the font colors for legibility. You can also change typography settings such as size, weight, and font-family as you see fit.
Finsemble's default look and feel makes use of an icon library called Font Finance (inspired by Font Awesome). font-finance is included in Finsemble's UI Library and can be imported into any component that you build.
Importing font-finance into a React component:
import "@finsemble/finsemble-ui/react/assets/css/font-finance.css";
Importing font-finance into a static HTML component:
@import url("../../../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>
Have a look at the font-finance reference sheet to see the available icons.
For a list of all Finsemble's UI Components and how to customize them, check out the Component Catalog.