From 56103427080932846a1d1572d4f7af8fdb18a678 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 24 Nov 2021 13:56:34 +0000 Subject: [PATCH 1/4] Making joinChannel, leaveCurrentChannel and getCurrentChannel functions optional --- docs/api/ref/DesktopAgent.md | 11 ++++++++--- docs/api/spec.md | 4 +++- src/api/DesktopAgent.ts | 9 ++++++--- 3 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index f7b52efdd..88753f12f 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 maangement functions joinChannel(channelId: string) : Promise; getCurrentChannel() : Promise; leaveCurrentChannel() : Promise; @@ -201,7 +202,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 @@ -289,7 +292,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. @@ -321,8 +325,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 5c0a9b309..94221b6a2 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -236,7 +236,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 SHOULD provide [`fdc3.joinChannel()`](ref/DesktopAgent#joinchannel), [`fdc3.getCurrentChannel()](ref/DesktopAgent#getcurrentchannel) and [`fdc3.leaveCurrentChannel()`](ref/DesktopAgent#leavecurrentchannel) functions as defined in the [Desktop Agent API reference](ref/DesktopAgent). + +Always, there SHOULD be a clear UX indicator of what channel an app is joined to. ### The 'global' Channel diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 6b449a6f6..212412836 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. + * Option 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 From 4e2373247b6377bec105ebca3d12181490e7d708 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 24 Nov 2021 13:58:55 +0000 Subject: [PATCH 2/4] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfbf2dee0..08fec405c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,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)) ### Deprecated ### Fixed From 4b557b75423ce50dac4314303ad94a8f0c64db3e Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 13 Dec 2021 20:31:26 +0000 Subject: [PATCH 3/4] typo --- docs/api/ref/DesktopAgent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 88753f12f..904bfe241 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -35,7 +35,7 @@ interface DesktopAgent { // channels getOrCreateChannel(channelId: string): Promise; getSystemChannels(): Promise>; - // optional channel maangement functions + // optional channel management functions joinChannel(channelId: string) : Promise; getCurrentChannel() : Promise; leaveCurrentChannel() : Promise; From 49073db0ec96031d57db0ac3f6bdaf7c4674c54b Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 21 Dec 2021 10:37:56 +0000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Matt Jamieson <10372+mattjamieson@users.noreply.github.com> --- docs/api/spec.md | 4 ++-- src/api/DesktopAgent.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/spec.md b/docs/api/spec.md index 94221b6a2..a7629a037 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -236,9 +236,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. 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 SHOULD provide [`fdc3.joinChannel()`](ref/DesktopAgent#joinchannel), [`fdc3.getCurrentChannel()](ref/DesktopAgent#getcurrentchannel) and [`fdc3.leaveCurrentChannel()`](ref/DesktopAgent#leavecurrentchannel) functions as defined in the [Desktop Agent API reference](ref/DesktopAgent). +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). -Always, there SHOULD be a clear UX indicator of what channel an app is joined to. +There SHOULD always be a clear UX indicator of what channel an app is joined to. ### The 'global' Channel diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 212412836..cfdfb226d 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -195,7 +195,7 @@ export interface DesktopAgent { getSystemChannels(): Promise>; /** - * Option 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. + * 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.