diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f511d4d5..7f0b6c5b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Updated copyright notices ([#467](https://github.com/finos/FDC3/pull/467)) * Adjusted wording in API spec and documentation to acknowledge the possibility of methods of intent resolution other than a resolver UI ([#461](https://github.com/finos/FDC3/pull/461)) * Moved the Icon type definition into the Types documentation page for consistency with other types. ([#493](https://github.com/finos/FDC3/pull/493) +* The `fdc3.joinChannel()`, `fdc3.getCurrentChannel()` and `fdc3.leaveCurrentChannel()` functions have been made optional for FDC3 API compliance, but are recommended through the application of the SHOULD keyword. ([#512](https://github.com/finos/FDC3/pull/512)) * All DesktopAgent and Channel API functions are now async for consistency, changing the return type of the `broadcast`, `addIntentListener`, `addContextListener` and `getInfo` functions ([#516](https://github.com/finos/FDC3/pull/516)) ### Deprecated diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 81961b990..02e233a5d 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -35,6 +35,7 @@ interface DesktopAgent { // channels getOrCreateChannel(channelId: string): Promise; getSystemChannels(): Promise>; + // optional channel management functions joinChannel(channelId: string) : Promise; getCurrentChannel() : Promise; leaveCurrentChannel() : Promise; @@ -203,7 +204,9 @@ A promise resolving to all the intents, their metadata and metadata about the ap getCurrentChannel() : Promise; ``` -Returns the `Channel` object for the current channel membership. Returns `null` if the app is not joined to a channel. +Optional function that returns the `Channel` object for the current channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. + +Returns `null` if the app is not joined to a channel. #### Examples @@ -291,7 +294,8 @@ const redChannel = systemChannels.find(c => c.id === 'red'); joinChannel(channelId: string) : Promise; ``` -Joins the app to the specified channel. +Optional function that joins the app to the specified channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly. + If an app is joined to a channel, all `fdc3.broadcast` calls will go to the channel, and all listeners assigned via `fdc3.addContextListener` will listen on the channel. If the channel already contains context that would be passed to context listeners added via `fdc3.addContextListener` then those listeners will be called immediately with that context. @@ -323,8 +327,9 @@ fdc3.joinChannel(selectedChannel.id); leaveCurrentChannel() : Promise; ``` -Removes the app from any channel membership. Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not joined to a channel. +Optional function that removes the app from any channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. +Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not joined to a channel. #### Examples diff --git a/docs/api/spec.md b/docs/api/spec.md index dc3e1219d..97866e614 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -258,7 +258,9 @@ When an app joins a channel, or adds a context listener when already joined to a It is possible that a call to join a channel could be rejected. If for example, the desktop agent wanted to implement controls around what data apps can access. -Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. Always, there SHOULD be a clear UX indicator of what channel an app is joined to. +Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. To support programmatic management of joined channels and the implementation of channel selector UIs other than those provided outside of the app, Desktop Agent implementations MAY provide [`fdc3.joinChannel()`](ref/DesktopAgent#joinchannel), [`fdc3.getCurrentChannel()](ref/DesktopAgent#getcurrentchannel) and [`fdc3.leaveCurrentChannel()`](ref/DesktopAgent#leavecurrentchannel) functions and if they do, MUST do so as defined in the [Desktop Agent API reference](ref/DesktopAgent). + +There SHOULD always be a clear UX indicator of what channel an app is joined to. #### Examples diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 997c3b1f2..cc631856b 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -195,7 +195,8 @@ export interface DesktopAgent { getSystemChannels(): Promise>; /** - * Joins the app to the specified channel. + * Optional function that joins the app to the specified channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly. + * * If an app is joined to a channel, all `fdc3.broadcast` calls will go to the channel, and all listeners assigned via `fdc3.addContextListener` will listen on the channel. * If the channel already contains context that would be passed to context listeners assed via `fdc3.addContextListener` then those listeners will be called immediately with that context. * An app can only be joined to one channel at a time. @@ -219,13 +220,15 @@ export interface DesktopAgent { getOrCreateChannel(channelId: string): Promise; /** - * Returns the `Channel` object for the current channel membership. + * Optional function that returns the `Channel` object for the current channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. + * * Returns `null` if the app is not joined to a channel. */ getCurrentChannel(): Promise; /** - * Removes the app from any channel membership. + * Optional function that removes the app from any channel membership. In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. + * * Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not on a channel. * ```javascript * //desktop-agent scope context listener