Skip to content

Commit 302eb0f

Browse files
kriswestkriswest
authored
Merge pull request #727 from finos/717-recommended-channels
717 Add a recommended set of user channels to the Standard
2 parents f7efe92 + 720e35a commit 302eb0f

5 files changed

Lines changed: 181 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
2222
* Added a Trademarks page to website to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534))
2323
* Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
2424
* Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
25+
* Added a recommended set of user channel definitions to the API docs and typescript sources ([#727](https://github.com/finos/FDC3/pull/726))
2526
* Added the optional exposure of originating app metadata to messages received via `addContextListener` and `addIntentListener` via the new `ContextMetadata` type. ([#725](https://github.com/finos/FDC3/pull/725))
2627
* Added the current app's `AppMetadata` to the `ImplementationMetadata` returned by `fdc3.getInfo()` allowing an app to retrieve its own metadata, according to the Desktop Agent ([#726](https://github.com/finos/FDC3/pull/726))
2728
* Added a context type representing a range of time (`fdc3.timerange`). ([#706](https://github.com/finos/FDC3/pull/706))

‎docs/api/spec.md‎

Lines changed: 88 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,90 @@ Calling `fdc3.broadcast` will now route context to the joined channel.
374374

375375
Channel implementations SHOULD ensure that context messages broadcast by an application on a channel are not delivered back to that same application if they are joined to the channel.
376376

377-
> Prior to FDC3 2.0, 'user' channels were known as 'system' channels. They were renamed in FDC 2.0 to reflect their intended usage, rather than the fact that they are created by system (which could also create 'app' channels). The `joinChannel` function was also renamed to `joinUserChannel` to clarify that it is only intended to be used to join 'user', rather than 'app', channels.
377+
> Prior to FDC3 2.0, 'user' channels were known as 'system' channels. They were renamed in FDC3 2.0 to reflect their intended usage, rather than the fact that they are created by system (which could also create 'app' channels). The `joinChannel` function was also renamed to `joinUserChannel` to clarify that it is only intended to be used to join 'user', rather than 'app', channels.
378+
379+
### Recommended User Channel Set
380+
381+
Desktop Agent implementations SHOULD use the following set of channels, to enable a consistent user experience across different implementations. Desktop Agent implementation MAY support configuration of the user channels.
382+
383+
> Note: Future versions of the FDC3 Standard may support connections between desktop agents, where differing user channel sets may cause user experience issues.
384+
385+
```javascript
386+
const recommendedChannels = [
387+
{
388+
id: 'fdc3.channel.1',
389+
type: 'user',
390+
displayMetadata: {
391+
name: 'Channel 1',
392+
color: 'red',
393+
glyph: '1',
394+
},
395+
},
396+
{
397+
id: 'fdc3.channel.2',
398+
type: 'user',
399+
displayMetadata: {
400+
name: 'Channel 2',
401+
color: 'orange',
402+
glyph: '2',
403+
},
404+
},
405+
{
406+
id: 'fdc3.channel.3',
407+
type: 'user',
408+
displayMetadata: {
409+
name: 'Channel 3',
410+
color: 'yellow',
411+
glyph: '3',
412+
},
413+
},
414+
{
415+
id: 'fdc3.channel.4',
416+
type: 'user',
417+
displayMetadata: {
418+
name: 'Channel 4',
419+
color: 'green',
420+
glyph: '4',
421+
},
422+
},
423+
{
424+
id: 'fdc3.channel.5',
425+
type: 'user',
426+
displayMetadata: {
427+
name: 'Channel 5',
428+
color: 'cyan',
429+
glyph: '5',
430+
},
431+
},
432+
{
433+
id: 'fdc3.channel.6',
434+
type: 'user',
435+
displayMetadata: {
436+
name: 'Channel 6',
437+
color: 'blue',
438+
glyph: '6',
439+
},
440+
},
441+
{
442+
id: 'fdc3.channel.7',
443+
type: 'user',
444+
displayMetadata: {
445+
name: 'Channel 7',
446+
color: 'magenta',
447+
glyph: '7',
448+
},
449+
},
450+
{
451+
id: 'fdc3.channel.8',
452+
type: 'user',
453+
displayMetadata: {
454+
name: 'Channel 8',
455+
color: 'purple',
456+
glyph: '8',
457+
},
458+
},
459+
];
460+
```
378461

379462
### Direct Listening and Broadcast on Channels
380463

@@ -422,9 +505,10 @@ if another application broadcasts to "my_custom_channel" (by retrieving it and b
422505
`PrivateChannels` are created to support the return of a stream of responses from a raised intent, or private dialog between two applications.
423506

424507
It is intended that Desktop Agent implementations:
425-
- - SHOULD restrict external apps from listening or publishing on this channel.
426-
- - MUST prevent `PrivateChannels` from being retrieved via `fdc3.getOrCreateChannel`.
427-
- - MUST provide the `id` value for the channel as required by the `Channel` interface.
508+
509+
- SHOULD restrict external apps from listening or publishing on this channel.
510+
- MUST prevent `PrivateChannels` from being retrieved via `fdc3.getOrCreateChannel`.
511+
- MUST provide the `id` value for the channel as required by the `Channel` interface.
428512

429513
The `PrivateChannel` type also supports synchronisation of data transmitted over returned channels. They do so by extending the `Channel` interface with event handlers which provide information on the connection state of both parties, ensuring that desktop agents do not need to queue or retain messages that are broadcast before a context listener is added and that applications are able to stop broadcasting messages when the other party has disconnected.
430514

‎src/api/RecommendedChannels.ts‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/**
2+
* SPDX-License-Identifier: Apache-2.0
3+
* Copyright FINOS FDC3 contributors - see NOTICE file
4+
*/
5+
6+
import { DisplayMetadata } from './DisplayMetadata';
7+
8+
/** Interface representing the data fields of a user channel, without the functions. */
9+
interface UserChannelTemplate {
10+
readonly id: string;
11+
readonly type: 'user';
12+
readonly displayMetadata?: DisplayMetadata;
13+
}
14+
15+
const recommendedChannels: Array<UserChannelTemplate> = [
16+
{
17+
id: 'fdc3.channel.1',
18+
type: 'user',
19+
displayMetadata: {
20+
name: 'Channel 1',
21+
color: 'red',
22+
glyph: '1',
23+
},
24+
},
25+
{
26+
id: 'fdc3.channel.2',
27+
type: 'user',
28+
displayMetadata: {
29+
name: 'Channel 2',
30+
color: 'orange',
31+
glyph: '2',
32+
},
33+
},
34+
{
35+
id: 'fdc3.channel.3',
36+
type: 'user',
37+
displayMetadata: {
38+
name: 'Channel 3',
39+
color: 'yellow',
40+
glyph: '3',
41+
},
42+
},
43+
{
44+
id: 'fdc3.channel.4',
45+
type: 'user',
46+
displayMetadata: {
47+
name: 'Channel 4',
48+
color: 'green',
49+
glyph: '4',
50+
},
51+
},
52+
{
53+
id: 'fdc3.channel.5',
54+
type: 'user',
55+
displayMetadata: {
56+
name: 'Channel 5',
57+
color: 'cyan',
58+
glyph: '5',
59+
},
60+
},
61+
{
62+
id: 'fdc3.channel.6',
63+
type: 'user',
64+
displayMetadata: {
65+
name: 'Channel 6',
66+
color: 'blue',
67+
glyph: '6',
68+
},
69+
},
70+
{
71+
id: 'fdc3.channel.7',
72+
type: 'user',
73+
displayMetadata: {
74+
name: 'Channel 7',
75+
color: 'magenta',
76+
glyph: '7',
77+
},
78+
},
79+
{
80+
id: 'fdc3.channel.8',
81+
type: 'user',
82+
displayMetadata: {
83+
name: 'Channel 8',
84+
color: 'purple',
85+
glyph: '8',
86+
},
87+
},
88+
];
89+
90+
export default recommendedChannels;

‎src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ export * from './api/IntentResolution';
1919
export * from './api/Listener';
2020
export * from './api/ImplementationMetadata';
2121
export * from './api/Methods';
22+
export * from './api/RecommendedChannels';
2223
export * from './context/ContextType';
2324
export * from './context/ContextTypes';
2425
export * from './intents/Intents';

‎website/blog/2017-09-25-testing-rss.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ authorFBID: 661277173
99
This should be truncated.
1010
<!--truncate-->
1111
This line should never render in XML.
12+

0 commit comments

Comments
 (0)
⚡