Channels
3.5.9Channels 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.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| mode | Mode | "single" | Retrieves the current Channel mode (single or multi Channel). Set by the io.Connect framework based on configuration. Available since io.Connect Browser 3.5 |
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.
It's recommended to use the getMyChannels() method instead, which can retrieve the contexts of the currently joined Channels both in single and in multi Channel mode.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | FDC3Options | Settings for retrieving an FDC3 context published in the io.Connect Channel. |
getMyChannelsmethod
Signature
() => Promise<ChannelContext[]>
Description
Retrieves a list with the contexts of the current Channels. Can be used both in single and in multi Channel mode. If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.
Available since io.Connect Browser 3.5
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 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
(options?: LeaveOptions) => Promise<void>
Description
Removes the current or a specified window from the current or a specified Channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | LeaveOptions | Options for leaving Channels. |
listmethod
mymethod
Signature
() => string
Description
Retrieves the name of the current Channel.
It's recommended to use the myChannels() method instead, which can retrieve the names of the currently joined Channels both in single and in multi Channel mode.
myChannelsmethod
Signature
() => string[]
Description
Retrieves a list with the names of the current Channels. Can be used both in single and in multi Channel mode. If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.
Available since io.Connect Browser 3.5
onChangedmethod
Signature
(callback: (channel: string) => void) => UnsubscribeFunction
Description
Notifies when the current window joins or leaves a Channel. Returns an unsubscribe function.
It's recommended to use the onChannelsChanged() method instead, which can handle Channel changes both in single and in multi Channel mode.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (channel: string) => void | Callback function for handling the event. Receives as an argument the name of the Channel which the window has joined or left. |
onChannelsChangedmethod
Signature
(callback: (channels: string[]) => void) => UnsubscribeFunction
Description
Notifies when the current window joins or leaves a Channel. Can be used both in single and in multi Channel mode. If used in single Channel mode, when the window joins a Channel, the array argument passed to the callback for handling the event will always contain a single member; when the window leaves the current Channel, the array will be empty. Returns an unsubscribe function.
Available since io.Connect Browser 3.5
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (channels: string[]) => void | Callback function for handling the event. Receives a list with the names of the currently joined Channels as an argument. |
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 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 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?: FDC3Context; } | 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 | ChannelMeta | Channel meta data (display name, color, image, etc.) |
||
| name | string | Unique name of the context. |
ChannelMetaobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| color | string | |||
| fdc3 | FDC3ChannelMeta | Provide to enable FDC3 channel support. |
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 |
FDC3ChannelDisplayMetadataobject
Description
Provide display hints for FDC3 User Channels intended to be visualized and selectable by end users.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| color | string | The color that should be associated within this channel when displaying
this channel in a UI, e.g: |
||
| glyph | string | A URL of an image that can be used to display this channel. |
||
| name | string | A user-readable name for this channel, e.g: |
FDC3ChannelMetaobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| displayMetadata | FDC3ChannelDisplayMetadata | |||
| id | string |
FDC3Contextobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| id | { [key: string]: any; } | Context data objects may contain equivalent key-value pairs for identifying and looking up context types, with optional identifiers to support various applications, though some types may require at least one identifier. |
||
| name | string | Context data objects may include a "name" property for additional information or display, with some derived types making it mandatory based on the use case. |
||
| type | string | Required field in the FDC3 context data schema, essential for routing context data and for intent discovery within the FDC3 ecosystem. |
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. |
LeaveOptionsobject
Description
Options for leaving Channels. If only a window ID is provided, the specified window will be removed from the current Channel if in single Channel mode, or from all currently joined Channels if in multi Channel mode. If you provide only the name of the Channel to leave, the current window will be removed from the specified Channel. If you don't provide an argument, the current window will be removed from the current Channel if in single Channel mode, or from all currently joined Channels if in multi Channel mode.
Available since io.Connect Browser 3.5Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| channel | string | Name of a Channel from which to remove the current or a specified window. |
||
| windowId | string | ID of an io.Connect Window which to remove from a Channel. |
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. |
Modeenumeration
Description
Channel mode. In single Channel mode, io.Connect Windows can join or leave only one Channel at a time. In multi Channel mode, io.Connect Windows can join or leave multiple Channels simultaneously. The Channel mode is set by the io.Connect framework based on configuration.
- "single"
- "multi"