Toolbar component

To install, run yarn template Toolbar

The Toolbar component is the hub of the smart desktop. It allows users to quickly and easily launch applications, search their data, and manage workspaces with the click of a button or the press of a hotkey. The Toolbar component is highly customizable. Let's look at its default structure and customization points, including menus and favorites.

High-level structure

The ToolbarShell React component wraps the Toolbar's visible components. It handles low-level communication with the rest of the smart desktop. The contents of the ToolbarShell are divided into three sections: left, center, and right. You can add or remove child components from any section, or remove sections themselves.

API

The Toolbar uses the following React components from the Finsemble UI API library.

Control	Summary
AdvancedAppLauncher	An advanced app launcher with folders and tags
AppLauncher	A simple pull down menu for launching apps
AutoArrange	A button for automatically arranging windows on the screen
DragHandle	The "draggable area" on the toolbar to move it around the screen
FavoritesShell	A section to display, launch, rearrange or remove favorites
MinimizeAll	A button that minimizes all Finsemble windows
RevealAll	A button that restores all Finsemble windows
Search	A drop down menu for federalized search across SearchProviders
ToolbarShell	A wrapper for the toolbar. All toolbar components must be contained in the ToolbarShell
ToolbarSection	A container section that intelligently resizes depending on the length of the toolbar
WorkspaceManagementMenu	A drop down for launching and managing workspaces

AppLauncher

The AppLauncher component is a toolbar menu that allows users to launch their apps and to add them as favorites.

FileMenu

The FileMenu is included in the toolbar template source code. It is an instance of Finsemble's Menu React component. See the menuing section for more details.

The FileMenu exposes several pre-built controls, listed in the next table. You can remove or rearrange them, and you can add your own items. Here's an example:

...
<Preferences />
<MenuItem onClick={() => alert("Hello world!")}>
    My Custom Menu Item
</MenuItem>
<SystemLog />
...

API

The File Menu uses these React components from the Finsemble UI API library:

Control	Summary
Preferences	An menu item that opens the Preferences window.
SystemLog	A menu item that opens the system log.
CentralLogger	A menu item that opens the central logger.
Documentation	A menu that opens this documentation site.
Restart	A menu item that restarts the SmartDesktop.
Reset	A menu item that resets the SmartDesktop to its initial state, destroying all workspaces, custom apps, etc (use with caution!).
Quit	A menu item that quits the SmartDesktop.

Favorites

"Favorites" let users launch their favorite workspaces or apps with a single click on the Toolbar. Favorites are implemented with two components: FavoritesShell is the area on the toolbar that contains the favorites, and FavoriteMaker is a component that lets users toggle a favorite on and off (the "star" that they press). FavoriteMaker is usually found inside a menu.

API

Favorites use the following React components from the Finsemble UI API library.

Control	Summary
FavoriteMaker	A "star" icon that toggles a favorite on and off
FavoritesShell	A container for favorites where users can launch and organize their favorites

Menuing

Drop down menus created with Finsemble's Menu component use Electron windows that are created when the menu opens and destroyed when it closes. Menu positioning is intelligent, appearing upward or downward depending on their location on the screen. Finsemble's menus emulate the desktop menu experience but are built with HTML5 and React. This gives you the power to put anything in a menu!

Behind the scenes, menus use React Portals to manage state across window borders and Finsemble's windowing primitives to manage location but you don't need to deal with any of that to create your own menu. Constructing a menu in Finsemble is as easy as creating a drop-down in DOM. Just use the following React components.

API

Menuing uses the following React components from the Finsemble UI API library.

Control	Summary
Menu	A component that creates a fully functioning drop down menu.
MenuContent	Advanced. The actual drop-down menu. All contents inside <MenuContent> will be displayed to the user
MenuToggle	Advanced. A button that opens and closes the menu.
MenuItem	Optional. A container that can be used within a menu. This allows cursor up/down navigation and can automatically close the menu on clicks.
MenuShell	Advanced. Provides a shell for the menuing mechanism. It creates and registers a menu {i.e. with the toolbar)}.

Creating Menus

<Menu id="MyMenuId" title="ClickMe">
    <div>Optional Title</div>
    <MenuItem>item #1</MenuItem>
    <MenuItem>item #2</MenuItem>
    <MenuItem>item #3</MenuItem>
    <div className="custom-div">You can put anything you want in a menu</div>
</Menu>

Advanced Menus

Sometimes you may need to create a complex menu. You can use the advanced components to gain finer control over menuing.

Here's how the menuing React components collaborate to create a drop-down menu:

Here is sample code for creating a menu using internal components:

<MenuShell id="MyMenuId">
    <MenuToggle>Custom Menu<MenuToggle/>
    <MenuContent>
        <div>Optional Title</div>
        <MenuItem>item #1</MenuItem>
        <MenuItem>item #2</MenuItem>
        <MenuItem>item #3</MenuItem>
        <div>You can put anything you want in a menu</div>
    </MenuContent>
</MenuShell>

Dashbar

note

To use the Dashbar you must install a custom Toolbar using the command yarn template Toolbar. This will add the Toolbar configuration to /public/configs/application/config.json which can then be modified to enable the Dashbar.

The Dashbar is an additional optional panel that displays in the Toolbar, where web pages/web apps can be displayed in real-time. Dashbar items are implemented using Electron's BrowserViews which can be arranged be the end user. Each view can be pre-assigned a width. Finsemble's global API (FSBL) is accessible to pages loaded in the Dashbar.

note

• FDC3 is not yet supported in Dashbar views. Use FSBL.Clients.RouterClient to tunnel FDC3 messages into and out of the Dashbar.
• Dashbar views automatically receive preloads that are set for the Toolbar. It is not currently possible to specify preloads for individual Dashbar views.

Here is an example Dashbar:

The Dashbar is enabled by adding the following config to your Toolbar's AppD entry. Dashbar properties are defined in the Toolbar's component config, and include the height of the dashbar and the widget divider width:

"window": {
    "data": {
        "dashbar": {
            "height": 150,
            "widgetDividerWidth": 1,
            "items": ["stockWidget"],
            "loadingIconUrl": "$moduleRoot/assets/img/Finsemble_Taskbar_Icon.png"
        }
    }
}

items specified which Dashbar items are loaded by default. Each item must reference an item specified in availableDashbarItems (see below).

Both height and widgetDividerWidth are expressed in pixels. Set to 0 to not display a divider.

The loadingIconUrl is optional and provides ability to show a custom icon or gif while widgets are loading.

note

The max height of the toolbar will be the calculation of component height + dashbar height. You must define a dashbar height for it to show. If dashbar height is not defined, the dashbar will not show regardless of what items are defined.

To add available Dashbar items, create an availableDashbarItems entry in public/configs/application/config.json.

"availableDashbarItems": {
    "stockWidget": {
        "title": "Stock Ticker",
        "url": "https://example.stock.ticker.com",
        "width": 200,
        "height": 200
    }
}

The title and url fields are required. You can optionally include a width or height to prevent the dashbar item from being wider or taller then the specified pixel value.

note

You can't extend the height of the Toolbar by setting its height property to a greater value than the Dashbar height. The view will be cut off unless you adjust the Dashbar's height.

You can also add disablePointerEvents to disable the ability to interact with items inside the dashbar.

note

Users can change the items the dashbar is displaying from the Dashbar section of User Preferences:

Download Manager

The Download Manager gives visibility and control over downloads from the web. You can access the Download Manager by clicking an icon on the toolbar:

]

note

If you've customized the toolbar, you need to add the Download button to your custom toolbar configuration. See DownloadButton for more info.

The Download Manager displays all downloads that users have initiated since Finsemble's last restart. Each download item displays information, such as filename and download progress, and allows for additional actions depending on the download state.

These actions are available depending on the state of a download:

State	Available actions
In progress	Pause, cancel
Paused	Resume, cancel
Cancelled/Failed	Remove from Download Manager
Completed	Show in folder, Remove from Download Manager

note

Currently you can't retry/resume a cancelled or failed download.

By default, when the user initiates a download, the Download Manager prompts them for a save location. You can change this behavior by setting a download location in the Preferences Panel in the File Menu > Preferences > General > Downloads. You can also access this menu from the settings icon on the top right of the Download Manager. The Download Manger uses this location for all future downloads until you specify a new location or until you set the option to prompt for each download.