Channels
3.4.6Channels are globally accessed named contexts that allow users to dynamically group apps, instructing them to work over the same shared data object. The Channels API enables you to:
- discover Channels - get the names and contexts of all Channels;
- navigate through Channels - get the current Channel, join and leave Channels, subscribe for the event which fires when the current Channel has changed;
- publish and subscribe - publish data to other apps on the same Channel and subscribe for Channel updates to react to data published by other apps;
The Channels API is accessible through the io.channels object.
APIobject
Description
Channels API.
Methods
addmethod
Signature
(info: ChannelDefinition) => Promise<ChannelContext>
Description
Adds a new Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| info | ChannelDefinition | Initial Channel context. |
allmethod
Signature
() => Promise<string[]>
Description
Returns a list of all channel names.
getmethod
Signature
(name: string, options?: FDC3Options) => Promise<ChannelContext>
Description
Returns the context of a given channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The name of the channel whose context to return. |
|
| options | FDC3Options | Settings for retrieving an FDC3 context published in the io.Connect Channel. |
getMymethod
Signature
(options?: FDC3Options) => Promise<ChannelContext>
Description
Retrieves the context of the current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | FDC3Options | Settings for retrieving an FDC3 context published in the io.Connect Channel. |
getRestrictionsmethod
Signature
(windowId?: string) => Promise<Restrictions>
Description
Retrieves the restrictions applied to the current window for publishing or subscribing to Channels. Pass a window ID to retrieve the restrictions for the specified window.
Available since version io.Connect Browser 3.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| windowId | string | ID of the window for which to retrieve the applied restrictions for publishing or subscribing to Channels. |
getWindowsOnChannelmethod
Signature
(channel: string) => Promise<WebWindow[]>
Description
Retrieves all windows on a specified Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| channel | string | The name of the Channel for which windows should be returned. |
getWindowsWithChannelsmethod
Signature
(filter?: WindowWithChannelFilter) => Promise<WindowOnChannelInfo[]>
Description
Retrieves all windows that can use Channels together with their current Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| filter | WindowWithChannelFilter | Filter describing which windows to retrieve. If no filter is supplied, will return all windows that can use Channels. |
joinmethod
Signature
(name: string, windowId?: string) => Promise<void>
Description
Joins a new channel by name. Leaves the current channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The name of the channel to join. |
|
| windowId | string | ID of a window which to join to a Channel. If not provided, will join the current window to the specified Channel. |
leavemethod
Signature
(config?: ChannelsLeaveConfig) => Promise<void>
Description
Leaves the current channels.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| config | ChannelsLeaveConfig | Settings for leaving channels. |
listmethod
mymethod
Signature
() => string
Description
Returns the name of the current channel.
onChangedmethod
Signature
(callback: (channel: string) => void) => UnsubscribeFunction
Description
Subscribes for the event which fires when a channel is changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (channel: string) => void | Callback function to handle channel changes. |
publishmethod
Signature
(data: any, options?: string | PublishOptions) => Promise<void>
Description
Updates the context of the current or a given channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| data | any | Data object with which to update the channel context. |
|
| options | string | PublishOptions | The name of the Channel to update, or an object containing the name of the Channel to update and a flag indicating whether the published data is an FDC3 context. If no options are provided, the current Channel will be updated. |
removemethod
Signature
(name: string) => Promise<void>
Description
Removes a Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The name of the Channel to remove. |
restrictmethod
Signature
(config: ChannelRestrictions) => Promise<void>
Description
Prevents or allows the current or another window to publish or subscribe to a specific Channel.
Available since version io.Connect Browser 3.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| config | ChannelRestrictions |
restrictAllmethod
Signature
(restrictions: RestrictionsConfig) => Promise<void>
Description
Prevents or allows the current or another window to publish or subscribe to all Channels.
Available since version io.Connect Browser 3.3
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| restrictions | RestrictionsConfig | Restrictions for publishing or subscribing to all Channels. |
subscribemethod
Signature
(callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => UnsubscribeFunction
Description
Tracks the data in the current channel. Persisted after a channel change. The callback isn't called when you publish the data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function to handle the received data. |
|
| options | FDC3Options | Settings for subscribing to an FDC3 context published in the io.Connect Channel. |
subscribeFormethod
Signature
(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options) => Promise<UnsubscribeFunction>
Description
Tracks the data in a given channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | The channel to track. |
|
| callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function to handle the received data. |
|
| options | FDC3Options | Settings for subscribing to an FDC3 context published in the io.Connect Channel. |
ChannelContextobject
Description
Channel context object.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| data | { [key: string]: any; fdc3?: Context; } | Channel data. |
||
| meta | any | Channel meta data (display name, color, image, etc.) |
||
| name | string | Unique name of the context. |
ChannelDefinitionobject
Description
Initial context for creating a channel runtime.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| data | any | Channel data. |
||
| meta | any | Channel meta data (display name, color, image, etc.) |
||
| name | string | Unique name of the context. |
ChannelRestrictionsobject
Description
Restrictions applied to a window for publishing or subscribing to a specific Channel.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| name | string | Name of the Channel for which the restrictions apply. |
||
| read | boolean | If |
||
| windowId | string | ID of the window for which apply the restrictions for publishing or subscribing to Channels. |
||
| write | boolean | If |
ChannelsLeaveConfigobject
Description
Options for leaving the Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| channel | string | Name of a channel which should be left. If not provided, will leave from all current channels. |
||
| windowId | string | ID of a window which to leave from a Channel. If not provided, will leave the current window from the current Channel |
FDC3Optionsobject
Description
Settings for retrieving and subscribing for FDC3 contexts published in an io.Connect Channel.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| contextType | string | Type of the FDC3 context to retrieve or to which to subscribe. |
PublishOptionsobject
Description
Options for updating a Channel context with the publish() method.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| fdc3 | boolean | Flag indicating whether the published data is an FDC3 context. If so, it must contain a required |
||
| name | string | The name of the Channel to update. If not provided, the current Channel will be updated. |
Restrictionsobject
Description
All restrictions applied to a window for publishing or subscribing to Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| channels | ChannelRestrictions[] | List of restrictions for publishing or subscribing to Channels. |
RestrictionsConfigobject
Description
Restrictions applied to a window for publishing or subscribing to all Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| read | boolean | If |
||
| windowId | string | ID of the window for which apply the restrictions for publishing or subscribing to Channels. |
||
| write | boolean | If |
WindowOnChannelInfoobject
Description
Describes a window that can use Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | string | Name of the app to which the window instance belongs. |
||
| channel | string | Name of the Channel to which the window is joined. |
||
| window | WebWindow | Describes the window instance. |
WindowWithChannelFilterobject
Description
Filter for retrieving windows that can use Channels.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | string | Name of the app whose window instances to retrieve. |
||
| channels | string[] | List of Channel names. Only the windows that are joined to one of the specified Channels will be retrieved. |
||
| windowIds | string[] | IDs of windows to retrieve. |