Skip to main content

Module: WorkspaceClient

The Workspace Client manages all calls to load, save, rename, and delete workspaces.

The Workspace Client uses the windowIdentifier parameter. Learn more about them here.

See the Workspace tutorial for an overview of using the Workspace Client.

Classes

Type Aliases

FinsembleEventHandler

Ƭ FinsembleEventHandler: (event: FinsembleEvent) => void

Type declaration

▸ (event): void

Parameters
NameType
eventFinsembleEvent
Returns

void


FinsembleEventParams

Ƭ FinsembleEventParams: Object

Type declaration

NameType
eventstring
handlerFunction
listenerGuidstring
sourcestring
sourceTypestring

GroupData

Ƭ GroupData: Object

Type declaration

NameType
isARectangle?boolean
isAlwaysOnTopboolean
isMovableboolean
topRightWindowstring
ungroupedAlwaysOnTopState?Record<string, Boolean>
windowNamesstring[]

Workspace

Ƭ Workspace: WorkspaceBase & { windows: string[] }

The complete data representation of a Workspace.


WorkspaceBase

Ƭ WorkspaceBase: Object

This interface represents base data that all workspace-type objects have in common and extend.

Type declaration

NameTypeDescription
groupsRecord<string, GroupData>-
namestringA string uniquely identifying the workspace from other workspaces. NOTE: Does not differentiate between instances of the same workspace. For that, see the guid property of the ActiveWorkspace type.
tabCollections?TabCollection[]-
type"workspace" | "template"Distinguishes normal workspaces from templates. Templates are workspaces that are distributed by Finsemble administrators to users and are not modified, much like a template document in Microsoft Office. The different behavior between workspaces and templates isn't yet implemented, but will be soon.
version"1.0.0"The version of the API schema. Used to maintain backward compatibility.

WorkspaceEventName

Ƭ WorkspaceEventName: "load-requested" | "load-complete" | "load-failed" | "load-interrupted" | "close-requested" | "close-complete" | "close-canceled" | "close-failed" | "save-requested" | "save-complete" | "save-failed"

Functions

addEventListener

addEventListener(event, handler): void

This provides the ability to listen to workspace events. The load-requested event provides a way to merge data into the workspace prior to loading. The close-requested and save-requested event, allow you to perform actions prior to the actual save and close. The rest of the events are informational only. To tell the workspace service to wait, you must call event.wait() in less than one second. Calling event.wait() will wait indefinitely. After event.wait() is called, event.done() must be called to resume operation. If the event is cancelable, event.cancel() may also be called after event.wait() to cancel the event. To send data event.done(data) must be called, otherwise done with no data is assumed.

// Sync examples:
FSBL.Clients.WorkspaceClient.addEventListener("close-requested", (event) => {
doSomething();
});
FSBL.Clients.WorkspaceClient.addEventListener("load-requested", (event) => {
const data = doSomething();
event.done(data);
});

// Async examples:
FSBL.Clients.WorkspaceClient.addEventListener(
"close-requested",
async (event) => {
event.wait();
await doSomething();
event.done();
},
);
FSBL.Clients.WorkspaceClient.addEventListener(
"load-requested",
async (event) => {
event.wait();
const data = await doSomething();
event.done(data);
},
);

Parameters

NameTypeDescription
eventWorkspaceEventNameThe workspace event to listen for
handlerFinsembleEventHandlerA function to handle the event

Returns

void


autoArrange

autoArrange(params, cb?): StandardPromise<void>

This method is an experimental feature in Finsemble Labs. Calling this method automatically arranges all windows on the user's screen into a grid-like pattern.

Parameters

NameTypeDescription
paramsanyParameters Unused
cb?StandardErrorCallback<void>The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>


bringWindowsToFront

bringWindowsToFront(params?, cb?): StandardPromise<void>

Brings all windows to the front, revealing any that are minimized.

await FSBL.Clients.WorkspaceClient.bringWindowsToFront();

Parameters

NameTypeDescription
params?Object
params.windowList?string[]Optional list of windows to bring to front, otherwise all workspace windows will be brought to front.
cb?StandardErrorCallback<void>The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>


createWorkspace

createWorkspace(workspaceName, params?, cb?): Promise<{ workspaceName: string }>

Creates a new workspace, returning a promise for the final name of the new workspace as a string. After creation, if "switchAfterCreation" is true, the new workspace becomes the active workspace.

If the requested name already exists, a new workspace will be created with the form "[name] (1)" (or "[name] (2)", etc.)

This example creates the workspace 'My Workspace'.

FSBL.Clients.WorkspaceClient.createWorkspace(
"My workspace",
{ switchAfterCreation: true },
function (err, response) {
if (!err) {
//Do something, such as notify the user that the workspace has been created.
}
},
);

Parameters

NameTypeDescription
workspaceNamestringName for new workspace. If the workspaceName is empty, the workspace is given the name "Untitled." Subsequent creations with empty strings would result in "Untitled1", "Untitled2", etc.
params?ObjectOptional params
params.switchAfterCreation?booleanWhether to switch to the new workspace after creating it. Defaults to true.
cb(err: any, result: { workspaceName: string }) => voidcb(err,response) With response, set to new workspace object if no error.

Returns

Promise<{ workspaceName: string }>


export

export(params, cb): Promise<unknown>

Gets a workspace definition in JSON form.

FSBL.Clients.WorkspaceClient.export(
{ workspaceName: "linker" },
function (err, workspaceDefinition) {
//do something with the workspace definition
},
);

Parameters

NameTypeDescription
paramsObject
params.workspaceNamestringThe name of the workspace you want to export.
cbFunctioncallback(error, workspaceDefinition)

Returns

Promise<unknown>


getActiveWorkspace

getActiveWorkspace(cb?): Promise<{ data: Workspace }>

Gets the currently active workspace. This function is useful for setting the initial state of a menu or dialog. It is used in the toolbar component to set the initial state.

FSBL.Clients.WorkspaceClient.getActiveWorkspace((err, response) => {
// do something with the response.
});

Parameters

NameTypeDescription
cb?StandardErrorCallback<{ data: Workspace }>The callback to be invoked after the method completes successfully.

Returns

Promise<{ data: Workspace }>


getWorkspaceActions

getWorkspaceActions(cb?): Record<string, string>

Gets workspace actions defined as constants. Allows users to filter updates

Parameters

NameTypeDescription
cb?StandardErrorCallback<Record<string, string>>The callback to be invoked after the method completes successfully.

Returns

Record<string, string>


getWorkspaceNames

getWorkspaceNames(cb?): Promise<string[]>

Returns a list of workspace names. This function returns the list of all the workspace.

FSBL.Clients.WorkspaceClient.getWorkspaceNames((err, response) => {
console.log(JSON.stringify(response, null, 2));
});

Output: ["Default Workspace", "Another workspace"];

Parameters

NameTypeDescription
cb?StandardErrorCallback<string[]>The callback to be invoked after the method completes successfully.

Returns

Promise<string[]>


getWorkspaces

getWorkspaces(cb?): Promise<unknown>

Returns the list of saved workspaces. This function is useful for setting the initial state of a menu or dialog.

FSBL.Clients.WorkspaceClient.getWorkspaces((err, response) => {
//do something with the array of workspace objects
console.log(response);
});

Parameters

NameTypeDescription
cb?FunctionThe callback to be invoked after the method completes successfully.

Returns

Promise<unknown>


import

import(params, cb?): Promise<Record<string, string>>

Adds a workspace definition to the list of available workspaces.

FSBL.Clients.WorkspaceClient.import(
{ force: false, workspaceJSONDefinition: workspaceDefinition },
function (err) {
if (!err) console.log("import success.");
},
);

Parameters

NameTypeDescription
paramsObject
params.forcebooleanWhether to overwrite any workspace of the same name that already exists
params.workspaceJSONDefinitionRecord<string, string | Workspace>The JSON for the workspace definition, as exported by the User Preferences menu in Finsemble Connect.
cb?Functioncb(err) where the operation was successful if !err; otherwise, err carries diagnostics

Returns

Promise<Record<string, string>>


isWorkspaceDirty

isWorkspaceDirty(cb?): Promise<boolean>

Checks to see if the workspace is dirty, i.e., if its state has been changed since the last save. If it's already dirty, the window doesn't need to compare its state to the saved state.

This example will let you know if the active workspace is dirty.

FSBL.Clients.WorkspaceClient.isWorkspaceDirty(function (err, response) {
if (response.data === true) {
//Do something like prompt the user if they'd like to save the currently loaded workspace before switching.
} else {
//Workspace is clean
}
});

Parameters

NameTypeDescription
cb?Functioncb(err,response) with response set to true if dirty and false otherwise (when no error).

Returns

Promise<boolean>


minimizeAll

minimizeAll(params?, cb?): StandardPromise<void>

Minimizes all windows.

await FSBL.Clients.WorkspaceClient.minimizeWindows();

Parameters

NameTypeDescription
params?Object
params.windowList?string[]Optional list of windows to minimize
cb?StandardErrorCallback<void>The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>


remove

remove(params, cb?): Promise<unknown>

Removes a workspace. Either the workspace object or its name must be provided.

The following examples both remove 'My Workspace' from the main menu and the default storage tied to the application.

FSBL.Clients.WorkspaceClient.remove(
{
name: "My Workspace",
},
function (err, response) {
//You typically won't do anything here. If you'd like to do something when a workspace change happens, we suggest listening on the `Finsemble.WorkspaceService.update` channel.
},
);

FSBL.Clients.WorkspaceClient.remove({
workspace: {
version: "1.0.0",
name: "My Workspace",
type: "workspace",
// ...
},
});

Parameters

NameTypeDescription
paramsObjectParameters object specifying the workspace name to remove, either directly as name or by passing in the workspace from which the name will be extracted.
params.name?stringThe workspace name removal is requested for.
params.workspace?ObjectA workspace data object.
params.workspace.namestring-
cb?FunctionCallback to fire after 'Finsemble.WorkspaceService.update' is transmitted.

Returns

Promise<unknown>


removeEventListener

removeEventListener(event, handler): void

Removes an event listener.

Parameters

NameTypeDescription
eventWorkspaceEventNameThe workspace event that is listened on
handlerFinsembleEventHandlerThe handler that is in effect

Returns

void


rename

rename(params, cb?): Promise<unknown>

Renames the workspace with the provided name. Also removes all references in storage to the old workspace's name. This method is used to rename workspaces. It is used in the main Menu component.

note

If you attempt to rename a Workspace to a name that already exists a ({next number}) will be added to the newName.

FSBL.Clients.WorkspaceClient.rename(
{
oldName: "My Workspace",
newName: "The best workspace",
removeOldWorkspace: true,
},
function (err, response) {
//Do something.
},
);

Parameters

NameTypeDescription
paramsObject
params.newNamestringWhat to rename the workspace to.
params.oldNamestringName of workspace to rename.
params.overwriteExisting?booleanWhether to overwrite an existing workspace.
params.removeOldWorkspace?booleanWhether to remove references to old workspace after renaming.
cb?FunctionThe callback to be invoked after the method completes successfully.

Returns

Promise<unknown>


save

save(cb?): Promise<unknown>

Saves the current active workspace.

This example persists the currently active workspace.

FSBL.Clients.WorkspaceClient.save(function (err) {
//Do something.
});

Parameters

NameTypeDescription
cb?FunctionThe callback to be invoked after the method completes successfully.

Returns

Promise<unknown>


saveAs

saveAs(params, cb?): Promise<unknown>

Saves the currently active workspace with the provided name.

This example persists the currently active workspace with the provided name.

FSBL.Clients.WorkspaceClient.saveAs(
{
name: "My Workspace",
},
function (err, response) {
//Do something.
},
);

Parameters

NameTypeDescription
paramsObject
params.force?booleanWhether to overwrite a workspace already saved with the provided name.
params.namestringThe new name you want to save the workspace under.
cb?FunctionThe callback to be invoked after the method completes successfully.

Returns

Promise<unknown>


switchTo

switchTo(params, cb?): Promise<{ data: Workspace }>

Switches to a workspace.

This example loads the workspace 'My Workspace' from the storage tied to the application.

FSBL.Clients.WorkspaceClient.switchTo(
{
name: "My Workspace",
},
function (err, response) {
//Do something.
},
);

Parameters

NameTypeDescription
paramsObject
params.namestringThe name of the workspace you want to switch to.
cb?StandardErrorCallback<{ data: Workspace }>The callback to be invoked after the method completes successfully.

Returns

Promise<{ data: Workspace }>