Merge pull request #329 from ChartIQ/deprecate-use-of-addContextListe…

…ner-with-only-a-handler

Deprecate use of addContextListener with only a handler

docs/api/ref/Channel.md

@@ -16,8 +16,11 @@ interface Channel {
   // methods
   broadcast(context: Context): void;
   getCurrentContext(contextType?: string): Promise<Context|null>;
-  addContextListener(handler: ContextHandler): Listener;
-  addContextListener(contextType: string, handler: ContextHandler): Listener;
+  addContextListener(contextType: string | null, handler: ContextHandler): Listener;
+  /**
+   * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+   */
+  addContextListener(handler: ContextHandler): Listener;  
 }
 ```
 
@@ -67,25 +70,26 @@ DisplayMetadata can be used to provide display hints for channels intended to be
 
 
 ### `addContextListener`
-
 ```ts
-public addContextListener(handler: ContextHandler): Listener;
+public addContextListener(contextType: string | null, handler: ContextHandler): Listener;
 ```
-
-Adds a listener for incoming contexts whenever a broadcast happens on the channel.
+Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel.
 
 ```ts
-public addContextListener(contextType: string, handler: ContextHandler): Listener;
+/**
+ * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+ */
+public addContextListener(handler: ContextHandler): Listener;
 ```
+Adds a listener for incoming contexts whenever a broadcast happens on the channel.
 
-Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel.
 
 #### Examples
 
 Add a listener for any context that is broadcast on the channel:
 
 ```ts
-const listener = channel.addContextListener(context => {
+const listener = channel.addContextListener(null, context => {
     if (context.type === 'fdc3.contact') {
         // handle the contact
     } else if (context.type === 'fdc3.instrument') => {
@@ -117,7 +121,7 @@ instrumentListener.unsubscribe();
 * [`Listener`](Listener)
 * [`ContextHandler`](ContextHandler)
 * [`broadcast`](#broadcast)
-* [`getCurrentContext`](#addcontextlistener)
+* [`getCurrentContext`](#getcurrentcontext)
 
 ### `broadcast`
 

docs/api/ref/Context.md

@@ -29,5 +29,5 @@ The `type` property of context objects is important for certain FDC3 operations,
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
 * [`DesktopAgent.raiseIntentForContext`](DesktopAgent#raiseIntentForContext)
 * [`Channel.broadcast`](Channel#broadcast)
-* [`Channel.getCurrentContext`](Cahnnel#getCurrentContext)
-* [`Channel.addContextListener`](Cahnnel#addContextListener)
+* [`Channel.getCurrentContext`](Channel#getCurrentContext)
+* [`Channel.addContextListener`](Channel#addContextListener)

docs/api/ref/DesktopAgent.md

@@ -13,8 +13,11 @@ interface DesktopAgent {
 
   // context
   broadcast(context: Context): void;
+  addContextListener(contextType: string | null, handler: ContextHandler): Listener;
+  /**
+   * @deprecated 'Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+   */
   addContextListener(handler: ContextHandler): Listener;
-  addContextListener(contextType: string, handler: ContextHandler): Listener;
 
   // intents
   findIntent(intent: string, context?: Context): Promise<AppIntent>;
@@ -60,16 +63,19 @@ if (window.fdc3) {
 ### `addContextListener`
 
 ```ts
+addContextListener(contextType: string | null, handler: ContextHandler): Listener;
+/**
+ * @deprecated 'Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+ */
 addContextListener(handler: ContextHandler): Listener;
-addContextListener(contextType: string, handler: ContextHandler): Listener;
 ```
 Adds a listener for incoming context broadcast from the Desktop Agent. If the consumer is only interested in
 a context of a particular type, they can use the relevant overload that allows the type to be specified.
 
 #### Examples
 ```js
 // any context
-const listener = fdc3.addContextListener(context => { ... });
+const listener = fdc3.addContextListener(null, context => { ... });
 
 // listener for a specific type
 const contactListener = fdc3.addContextListener('fdc3.contact', contact => { ... });
@@ -233,7 +239,7 @@ Returns a Channel object for the specified channel, creating it (as an _App_ cha
 ```js
 try {
   const myChannel = await fdc3.getOrCreateChannel("myChannel");
-  const myChannel.addContextListener(context => {});
+  const myChannel.addContextListener(null, context => {});
 }
 catch (err){
   //app could not register the channel
@@ -303,13 +309,13 @@ Removes the app from any channel membership.  Context broadcast and listening th
 
 ```js
 //desktop-agent scope context listener
-const fdc3Listener = fdc3.addContextListener(context => {});
+const fdc3Listener = fdc3.addContextListener(null, context => {});
 
 await fdc3.leaveCurrentChannel();
 //the fdc3Listener will now cease recieving context
 
 //listening on a specific channel though, will continue to work
-redChannel.addContextListener(channelListener);
+redChannel.addContextListener(null, channelListener);
 
 ```
 

docs/api/spec.md

@@ -280,7 +280,7 @@ const appChannel = await fdc3.getOrCreateChannel('my_custom_channel');
 // get the current context of the channel
 const current = await appChannel.getCurrentContext();
 // add a listener
-appChannel.addContextListener(context => {...});
+appChannel.addContextListener(null, context => {...});
 // broadcast to the channel
 appChannel.broadcast(context);
 

src/api/Channel.ts

@@ -61,11 +61,15 @@ export interface Channel {
 
   /**
    * Adds a listener for incoming contexts whenever a broadcast happens on this channel.
+   * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`.
    */
   addContextListener(handler: ContextHandler): Listener;
 
   /**
    * Adds a listener for incoming contexts of the specified context type whenever a broadcast happens on this channel.
    */
-  addContextListener(contextType: string, handler: ContextHandler): Listener;
+  addContextListener(
+    contextType: string | null,
+    handler: ContextHandler
+  ): Listener;
 }

src/api/DesktopAgent.ts

@@ -148,13 +148,17 @@ export interface DesktopAgent {
 
   /**
    * Adds a listener for incoming context broadcast from the Desktop Agent.
+   * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`.
    */
   addContextListener(handler: ContextHandler): Listener;
 
   /**
    * Adds a listener for the broadcast of a specific type of context object.
    */
-  addContextListener(contextType: string, handler: ContextHandler): Listener;
+  addContextListener(
+    contextType: string | null,
+    handler: ContextHandler
+  ): Listener;
 
   /**
    * Retrieves a list of the System channels available for the app to join