Finsemble includes a set of ready-made components to build your smart desktop. 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 smart desktop. 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 smart desktop'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 SmartDessmart desktopktop'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 smart desktop'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 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";
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.