Class: LinkerClient

Linker Client

Public API for the Linker Service

The Linker API provides a mechanism for synchronizing components on a piece of data. For instance, a user might want to link multiple components by stock symbol. Using the Linker API, a developer could enable their component to participate in this synchronization. The developer would use LinkerClient#subscribe to receive synchronization events, and they would use LinkerClient#publish to send them. The Linker API is inherently similar to the Router Client's pub/sub mechanism. The primary difference is that the Linker API is designed for end-user interaction. By exposing the Linker API, developers allow end users to create and destroy linkages at run-time.

In order for components to be linked, they 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 that a "symbol" looks like, for instance, {symbol:"IBM"}. The Linker API doesn't proscribe any specific format for context or set of labels (some would call this a "taxonomy"). See OpenFin's FDC3 project for an emerging industry standard taxonomy.

End users create linkages by assigning components to "channels." Our default implementation represents channels by color. When a component is assigned to the purple channel, publish and subscribe messages are only received by other components assigned to that channel. If you're using Finsemble's built-in Linker component, you won't have to code this. The Linker component does the work of assigning and unassigning its associated component to the selected channel. However, the Linker API exposes functionality so that you can manage channels programatically if you choose. You could use these functions to build your own Linker component using a different paradigm, or intelligently link components based on your own business logic. Note: it is not necessary to stick to a color convention. Channels are simple strings and so can be anything.

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 (DistributedStoreClient) to maintain this information and also persists the information to workspaces (WorkspaceClient).

See more on using the Linker API at our Linking tutorial.

Methods

getAllChannels
(cb){array}
clients/linkerClient.js, line 282

Returns all available Linker channels

Since:
  • 2.3 deprecated getAllGroups
Name Type Description
cb function optional

Optional callback to retrieve returned results asynchyronously

Returns:
Type Description
array An array of all channels. Each array item is {name:channelName} plus any other optional fields such as color.
Example
LinkerClient.getAllChannels()

getLinkedComponents
(params, cb){array}
clients/linkerClient.js, line 404

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.

Since:
  • 2.3 deprecated getLinkedWindows
Name Type Description
params object

Optional

Name Type Description
channels array

Restrict to these channels.

componentTypes array

Restrict to these componentTypes

windowIdentifier windowIdentifier

Restrict to this component

cb function optional

Optional callback to retrieve returned results asynchyronously

Returns:
Type Description
array An array of linked components, their windows, and their linked channels
Examples
Get all components linked to a given component
LinkerClient.getLinkedComponents({windowIdentifier: wi});
Get all components linked to channel "purple"
LinkerClient.getLinkedComponents({channels: ['purple']});
// Response format: [{windowName: 'Window Name', componentType: 'Component Type', uuid: 'uuid', channels: ['purple'] }, ..]

getState
(windowIdentifier, cb){LinkerClient~state}
clients/linkerClient.js, line 296

Retrieve all channels linked to the requested component. Also returns all available channels.

Since:
  • 2.3 deprecated getGroups, no longer supports a callback
Name Type Description
windowIdentifier windowIdentifier optional

Which component, or null for the current window.

cb function optional

Optional callback to retrieve returned results asynchyronously

Returns:
Type Description
LinkerClient~state The current state: linked channels, all channels
Example
var state=LinkerClient.getState(windowIdentifier)

linkToChannel
(channel, windowIdentifier, cb){LinkerClient~state}
clients/linkerClient.js, line 201

Add a component to a Linker channel programatically. Components will begin receiving any new contexts published to this channel but will not receive the currently established context.

Since:
  • 2.3 deprecated addToGroup
Name Type Description
channel string | array

The name of the channel to link our component to, or an array of names.

windowIdentifier windowIdentifier optional

Window Identifier for the component (optional). Current window if left null.

cb function optional

Optional callback to retrieve returned results asynchyronously

Returns:
Type Description
LinkerClient~state The new state: linked channels, all channels
Example
LinkerClient.linkToChannel("purple", null); // Link current window to channel "purple"
LinkerClient.linkToChannel("purple", windowIdentifier); // Link the requested window to channel "purple"

onStateChange
(cb)
clients/linkerClient.js, line 510

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 function

{null, LinkerClient~state}

Example
FSBL.Clients.LinkerClient.onStateChange(function(err, response){
   if(response.channels){
		console.log("Printout of channel status ", response.channels);
	}
});

publish
(params, cb)
clients/linkerClient.js, line 352

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 Object
Name Type Description
dataType String

The data type being sent

data any

the data ("context") being transmitted

channels Array optional

Optionally specify which channels to publish this piece of data. This overrides the default which is to publish to all linked channels.

cb function optional

Optional callback to make the function asynchronous (no data or errors are returned)

Example
LinkerClient.publish({dataType:"symbol",data:"AAPL"})

subscribe
(dataType, cb)
clients/linkerClient.js, line 375

Registers a client for a specific data type that is sent to a channel.

Name Type Description
dataType String
cb function optional

A function to be called once the linker receives the specific data.

Example
LinkerClient.subscribe("symbol", function(data){
		console.log("New symbol received from a remote component " + data);
	  });

unlinkFromChannel
(channel, windowIdentifier, cb){LinkerClient~state}
clients/linkerClient.js, line 242

Unlinks a component from a Linker channel.

Since:
  • 2.3 deprecated removeFromGroup
Name Type Description
channel string | array

Channel to remove, or an array of channels. If null, then all channels will be removed.

windowIdentifier windowIdentifier optional

Window Identifier for the client (optional). Current window if left null.

cb function optional

Optional callback to retrieve returned results asynchyronously

Returns:
Type Description
LinkerClient~state Returns the new state: linked channels, all channels
Example
LinkerClient.unlinkFromChannel("purple", null); // Unlink the current window from channel "purple"
LinkerClient.unlinkFromChannel("purple", windowIdentifier) // Unlink the requested window form channel "purple"

unsubscribe
(dataType, cb)
clients/linkerClient.js, line 335

Remove all listeners for the specified dataType.

Name Type Description
dataType String

The data type be subscribed to

cb function optional

Optional callback to retrieve returned results asynchyronously (empty object)

Example
LinkerClient.unsubscribe("symbol");

Type Definitions

channelsCB
(err, channels)
clients/linkerClient.js, line 770

Callback that returns a list of channels in the responseMessage

Name Type Description
err Object

Error message, or null if no error

channels Array

List of channels

state
(channels, allChannels)
clients/linkerClient.js, line 785

A list of enabled channels and a list of all channels

Name Type Description
channels Array

List of all channels linked to the requested component

allChannels Array

List of all available channels

stateCB
(err, channels, allChannels)
clients/linkerClient.js, line 777

Callback that returns a new LinkerClient~state

Name Type Description
err Object

Error message, or null if no error

channels Array

List of all channels linked to the requested component

allChannels Array

List of all available channels