PR comments

docs/development/core/public/kibana-plugin-public.contextsetup.createcontextcontainer.md

@@ -4,14 +4,14 @@
 
 ## ContextSetup.createContextContainer() method
 
-Creates a new [ContextContainer](./kibana-plugin-public.contextcontainer.md) for a service owner.
+Creates a new [IContextContainer](./kibana-plugin-public.icontextcontainer.md) for a service owner.
 
 <b>Signature:</b>
 
 ```typescript
-createContextContainer<TContext extends {}, THandlerReturn, THandlerParmaters extends any[] = []>(): ContextContainer<TContext, THandlerReturn, THandlerParmaters>;
+createContextContainer<TContext extends {}, THandlerReturn, THandlerParmaters extends any[] = []>(): IContextContainer<TContext, THandlerReturn, THandlerParmaters>;
 ```
 <b>Returns:</b>
 
-`ContextContainer<TContext, THandlerReturn, THandlerParmaters>`
+`IContextContainer<TContext, THandlerReturn, THandlerParmaters>`
 

docs/development/core/public/kibana-plugin-public.contextsetup.md

@@ -16,15 +16,15 @@ export interface ContextSetup
 
 |  Method | Description |
 |  --- | --- |
-|  [createContextContainer()](./kibana-plugin-public.contextsetup.createcontextcontainer.md) | Creates a new [ContextContainer](./kibana-plugin-public.contextcontainer.md) for a service owner. |
+|  [createContextContainer()](./kibana-plugin-public.contextsetup.createcontextcontainer.md) | Creates a new [IContextContainer](./kibana-plugin-public.icontextcontainer.md) for a service owner. |
 
 ## Remarks
 
-A [ContextContainer](./kibana-plugin-public.contextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares.
+A [IContextContainer](./kibana-plugin-public.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares.
 
 Contexts providers are executed in the order they were registered. Each provider gets access to context values provided by any plugins that it depends on.
 
-In order to configure a handler with context, you must call the [ContextContainer.createHandler()](./kibana-plugin-public.contextcontainer.createhandler.md) function and use the returned handler which will automatically build a context object when called.
+In order to configure a handler with context, you must call the [IContextContainer.createHandler()](./kibana-plugin-public.icontextcontainer.createhandler.md) function and use the returned handler which will automatically build a context object when called.
 
 When registering context or creating handlers, the \_calling plugin's id\_ must be provided. Note this should NOT be the context service owner, but the plugin that is actually registering the context or handler.
 
@@ -36,13 +36,13 @@ class MyPlugin {
   setup(core) {
     this.contextContainer = core.context.createContextContainer();
     return {
-      registerContext(plugin, contextName, provider) {
-        this.contextContainer.registerContext(plugin, contextName, provider);
+      registerContext(pluginId, contextName, provider) {
+        this.contextContainer.registerContext(pluginId, contextName, provider);
       },
-      registerRoute(plugin, path, handler) {
+      registerRoute(pluginId, path, handler) {
         this.handlers.set(
           path,
-          this.contextContainer.createHandler(plugin, handler)
+          this.contextContainer.createHandler(pluginId, handler)
         );
       }
     }
@@ -56,14 +56,14 @@ class MyPlugin {
   setup(core) {
     this.contextContainer = core.context.createContextContainer();
     return {
-      registerContext(plugin, contextName, provider) {
-        // This would leak this context to all handlers rather tha only plugins that depend on the calling plugin.
+      registerContext(pluginId, contextName, provider) {
+        // This would leak this context to all handlers rather that only plugins that depend on the calling plugin.
         this.contextContainer.registerContext('my_plugin', contextName, provider);
       },
-      registerRoute(plugin, path, handler) {
+      registerRoute(pluginId, path, handler) {
         this.handlers.set(
           path,
-          // the handler will not receive any contexts provided by other dependencies of the calling plugin.
+          // This handler will not receive any contexts provided by other dependencies of the calling plugin.
           this.contextContainer.createHandler('my_plugin', handler)
         );
       }
@@ -115,14 +115,15 @@ class VizRenderingPlugin {
     return {
       registerContext: this.contextContainer.registerContext,
 
-      // The handler can now be called directly with only an `HTMLElement` and will automaticallly
-      // have the `context` argument supplied.
       renderVizualization: (renderMethod: string, domElement: HTMLElement) => {
         if (!this.vizRenderer.has(renderMethod)) {
           throw new Error(`Render method '${renderMethod}' has not been registered`);
         }
 
-        return this.vizRenderers.get(renderMethod)(domElement);
+        // The handler can now be called directly with only an `HTMLElement` and will automatically
+        // have a new `context` object created and populated by the context container.
+        const handler = this.vizRenderers.get(renderMethod)
+        return handler(domElement);
       }
     };
   }

docs/development/core/public/kibana-plugin-public.icontextcontainer.createhandler.md

@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [IContextContainer](./kibana-plugin-public.icontextcontainer.md) &gt; [createHandler](./kibana-plugin-public.icontextcontainer.createhandler.md)
+
+## IContextContainer.createHandler() method
+
+Create a new handler function pre-wired to context for the plugin.
+
+<b>Signature:</b>
+
+```typescript
+createHandler(pluginId: string, handler: IContextHandler<TContext, THandlerReturn, THandlerParameters>): (...rest: THandlerParameters) => Promisify<THandlerReturn>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  pluginId | <code>string</code> | The plugin ID for the plugin that registers this handler. |
+|  handler | <code>IContextHandler&lt;TContext, THandlerReturn, THandlerParameters&gt;</code> | Handler function to pass context object to. |
+
+<b>Returns:</b>
+
+`(...rest: THandlerParameters) => Promisify<THandlerReturn>`
+
+A function that takes `THandlerParameters`<!-- -->, calls `handler` with a new context, and returns a Promise of the `handler` return value.
+

docs/development/core/public/kibana-plugin-public.icontextcontainer.md

@@ -0,0 +1,76 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [IContextContainer](./kibana-plugin-public.icontextcontainer.md)
+
+## IContextContainer interface
+
+An object that handles registration of context providers and configuring handlers with context.
+
+<b>Signature:</b>
+
+```typescript
+export interface IContextContainer<TContext extends {}, THandlerReturn, THandlerParameters extends any[] = []> 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [createHandler(pluginId, handler)](./kibana-plugin-public.icontextcontainer.createhandler.md) | Create a new handler function pre-wired to context for the plugin. |
+|  [registerContext(pluginId, contextName, provider)](./kibana-plugin-public.icontextcontainer.registercontext.md) | Register a new context provider. |
+
+## Remarks
+
+A [IContextContainer](./kibana-plugin-public.icontextcontainer.md) can be used by any Core service or plugin (known as the "service owner") which wishes to expose APIs in a handler function. The container object will manage registering context providers and configuring a handler with all of the contexts that should be exposed to the handler's plugin. This is dependent on the dependencies that the handler's plugin declares.
+
+Contexts providers are executed in the order they were registered. Each provider gets access to context values provided by any plugins that it depends on.
+
+In order to configure a handler with context, you must call the [IContextContainer.createHandler()](./kibana-plugin-public.icontextcontainer.createhandler.md) function and use the returned handler which will automatically build a context object when called.
+
+When registering context or creating handlers, the \_calling plugin's id\_ must be provided. Note this should NOT be the context service owner, but the plugin that is actually registering the context or handler.
+
+```ts
+// GOOD
+class MyPlugin {
+  private readonly handlers = new Map();
+
+  setup(core) {
+    this.contextContainer = core.context.createContextContainer();
+    return {
+      registerContext(pluginId, contextName, provider) {
+        this.contextContainer.registerContext(pluginId, contextName, provider);
+      },
+      registerRoute(pluginId, path, handler) {
+        this.handlers.set(
+          path,
+          this.contextContainer.createHandler(pluginId, handler)
+        );
+      }
+    }
+  }
+}
+
+// BAD
+class MyPlugin {
+  private readonly handlers = new Map();
+
+  setup(core) {
+    this.contextContainer = core.context.createContextContainer();
+    return {
+      registerContext(pluginId, contextName, provider) {
+        // This would leak this context to all handlers rather that only plugins that depend on the calling plugin.
+        this.contextContainer.registerContext('my_plugin', contextName, provider);
+      },
+      registerRoute(pluginId, path, handler) {
+        this.handlers.set(
+          path,
+          // This handler will not receive any contexts provided by other dependencies of the calling plugin.
+          this.contextContainer.createHandler('my_plugin', handler)
+        );
+      }
+    }
+  }
+}
+
+```
+

docs/development/core/public/kibana-plugin-public.icontextcontainer.registercontext.md

@@ -0,0 +1,34 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [IContextContainer](./kibana-plugin-public.icontextcontainer.md) &gt; [registerContext](./kibana-plugin-public.icontextcontainer.registercontext.md)
+
+## IContextContainer.registerContext() method
+
+Register a new context provider.
+
+<b>Signature:</b>
+
+```typescript
+registerContext<TContextName extends keyof TContext>(pluginId: string, contextName: TContextName, provider: IContextProvider<TContext, TContextName, THandlerParameters>): this;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  pluginId | <code>string</code> | The plugin ID for the plugin that registers this context. |
+|  contextName | <code>TContextName</code> | The key of the <code>TContext</code> object this provider supplies the value for. |
+|  provider | <code>IContextProvider&lt;TContext, TContextName, THandlerParameters&gt;</code> | A [IContextProvider](./kibana-plugin-public.icontextprovider.md) to be called each time a new context is created. |
+
+<b>Returns:</b>
+
+`this`
+
+The [IContextContainer](./kibana-plugin-public.icontextcontainer.md) for method chaining.
+
+## Remarks
+
+The value (or resolved Promise value) returned by the `provider` function will be attached to the context object on the key specified by `contextName`<!-- -->.
+
+Throws an exception if more than one provider is registered for the same `contextName`<!-- -->.
+