Class: LinkerClient
Linker Client (Finsemble Workspaces)
The Linker API allows components to synchronize on a piece of data. For instance, an end user can use the Linker to link multiple components by stock symbol. Use the Linker API to enable your components to participate in this synchronization.
In order for components to be linked, the components must understand the data format that will be passed between them (the "context"), and agree on a label that identifies that format (the dataType
).
For instance, components might choose to publish and subscribe to a dataType
called "symbol".
They would then also need to agree what a "symbol" looks like, for instance, {symbol:"IBM"}
.
The Linker API doesn't proscribe any specific format for context or set of labels.
Behind the scenes, the Linker Service coordinates Linker activity between components. It keeps track of the available channels and channel assignments. It uses a dedicated store (the Distributed Store) to maintain this information and also persists the information to workspaces (Workspace Client).
The Linker Client frequently uses the parameters windowIdentifier
and componentType
. Learn more about them here.
For more information, see the Linking tutorial.
Methods
-
addEventListener(event, handler)
-
Name Type Description event
string handler
Function -
getAllChannels(cb)
-
Returns all available Linker channels.
Name Type Description cb
Function optional Optional. Callback to retrieve returned results asynchronously.
Examples
Get all channels synchronously
let groups = FSBL.Clients.LinkerClient.getAllChannels();
Get all channels asynchronously
FSBL.Clients.LinkerClient.getAllChannels((err, channels) => { ... });
-
getLinkedComponents(params, cb)
-
Retrieves an array of all components with links that match the given parameters. If no parameters are specified, all windows with established links will be returned.
Name Type Description params
Optional
Name Type Description channels
string[] optional Restrict to these channels.
componentTypes
string[] optional Restrict to these componentTypes. The componentType is a key in the finsemble.components configuration object.
windowIdentifier
identifier optional Restrict to this component.
cb
StandardCallback The callback to be invoked if the method fails.
Examples
Get all components linked to a given component
FSBL.Clients.LinkerClient.getLinkedComponents({ windowIdentifier: wi });
Get all components linked to channel "group 1"
FSBL.Clients.LinkerClient.getLinkedComponents({ channels: ['group1'] }); // Response format: [{windowName: 'Window Name', componentType: 'Component Type', uuid: 'uuid', channels: ['group1'] }]
-
getLinkedWindows(params, cb)
-
Retrieves an array of all components with links that match the given parameters. If no parameters are specified, all windows with established links will be returned.
Name Type Description params
optional Optional
Name Type Description channels
string[] optional Restrict to these channels.
client
any optional Alias for windowIdentifier.
componentTypes
string[] optional Restrict to these componentTypes. The componentType is a key in the finsemble.components configuration object.
groups
string[] optional Alias for channels.
windowIdentifier
identifier optional Restrict to this component.
cb
StandardCallback The callback to be invoked if the method fails.
Examples
Get all components linked to a given component
FSBL.Clients.LinkerClient.getLinkedWindows({windowIdentifier: wi});
Get all Windows linked to channel "group1"
FSBL.Clients.LinkerClient.getLinkedComponents({ channels: ['group1'] }); // Response format: [{ windowName: 'Window Name', componentType: 'Component Type', uuid: 'uuid', channels: ['group1'] }]
-
getState(windowIdentifier, cb)
-
Retrieve all channels linked to the requested component. Also returns all available channels.
Name Type Description windowIdentifier
WindowIdentifier Name Type Description componentType
string optional The type of component
uuid
string optional Optional uuid of a particular application process
windowName
string The name of the physical HTML window, or a reference to a native window that was launched with Assimilation service
windowType
string optional cb
StandardCallback The callback to be invoked if the method fails.
Example
var state=LinkerClient.getState(windowIdentifier)
-
linkToChannel(channel, windowIdentifier, cb)
-
Add a component to a Linker channel programmatically. Components will begin receiving any new contexts published to this channel but will not receive the currently established context.
Name Type Description channel
string | string[] The name of the channel to link our component to, or an array of names.
windowIdentifier
WindowIdentifier Name Type Description componentType
string optional The type of component
uuid
string optional Optional uuid of a particular application process
windowName
string The name of the physical HTML window, or a reference to a native window that was launched with Assimilation service
windowType
string optional cb
Function optional Optional. Callback to retrieve returned results asynchronously.
Example
FSBL.Clients.LinkerClient.linkToChannel("group3", null); // Link current window to channel. FSBL.Clients.LinkerClient.linkToChannel("group3", windowIdentifier); // Link the requested window to channel.
-
onStateChange(cb)
-
Use this method to register a callback which will be called whenever the state of the Linker changes. This will be called whenever a user links or unlinks your component to a channel.
Name Type Description cb
StandardCallback The callback to be invoked if the method fails.
Example
FSBL.Clients.LinkerClient.onStateChange(function(err, response){ if(response.channels){ console.log("Printout of channel status ", response.channels); } });
-
openLinkerWindow(cb)
-
Opens the Linker window.
Name Type Description cb
any The callback to be invoked after the method completes successfully.
-
publish(params, cb)
-
Publish a piece of data. The data will be published to all channels that the component is linked to. Foreign components that are linked to those channels will receive the data if they have subscribed to this dataType. They can then use that data to synchronize their internal state. See
LinkerClient#subscribe
.Name Type Description params
Name Type Description channels
string[] optional Optional. Specifies which channels publish this piece of data. This overrides the default which is to publish to all linked channels.
data
any The data ("context") being transmitted.
dataType
string A string representing the data type being sent.
cb
StandardCallback The callback to be invoked if the method fails.
Example
FSBL.Clients.LinkerClient.publish({ dataType:"symbol", data:"AAPL" })
-
removeEventListener(event, handler)
-
Removes an event listener added by addEventListener
Name Type Description event
any An event that was used with addEventListener to add a listener
handler
any The handler that was used with addEventListener for the event
-
subscribe(dataType, cb)
-
Registers a client for a specific data type that is sent to a channel. Calling `subscribe` multiple times adds additional handlers. A component may be subscribed to a maximum of six channels at the same time.
Name Type Description dataType
string A string representing the data type to subscribe to.
cb
Function A function to be called once the Linker receives the specific data. Use response.originatedHere() to determine if the calling window is also the publisher
Example
FSBL.Clients.LinkerClient.subscribe("symbol", function(error, response) { if (error) { Logger.system.error("Error receiving publish from dataType symbol"); } else { if (response.originatedHere()) { Logger.system.warn("Received linker publish from subscribed window, ignoring"); } else { const data = response.data; // Logic to perform with data } } });
-
unSubscribe(dataType, cb)
-
Remove all listeners for the specified dataType.
Name Type Description dataType
string The data type to which the component is subscribed.
cb
Function Example
FSBL.Clients.LinkerClient.unsubscribe("symbol");
-
unlinkFromChannel(channel, windowIdentifier, cb)
-
Unlinks a component from a Linker channel.
Name Type Description channel
string | string[] Channel to remove, or an array of channels. If null, then all channels will be removed.
windowIdentifier
WindowIdentifier Name Type Description componentType
string optional The type of component
uuid
string optional Optional uuid of a particular application process
windowName
string The name of the physical HTML window, or a reference to a native window that was launched with Assimilation service
windowType
string optional cb
Function optional Optional. Callback to retrieve returned results asynchronously.
Example
FSBL.Clients.LinkerClient.unlinkFromChannel("group1", null); // Unlink the current window from channel "group1" FSBL.Clients.LinkerClient.unlinkFromChannel("group1", windowIdentifier) // Unlink the requested window from channel "group1"
-
unsubscribe(dataType, cb)
-
Remove all listeners for the specified dataType.
Name Type Description dataType
string The data type to which the component is subscribed.
cb
Function optional Optional. The function that was passed to subscribe. If not specified, all listeners will be deleted.
Example
FSBL.Clients.LinkerClient.unsubscribe("symbol");