Skip to content

Commit

Permalink
PR comments
Browse files Browse the repository at this point in the history
  • Loading branch information
joshdover committed Jul 26, 2019
1 parent df757ce commit d453b78
Show file tree
Hide file tree
Showing 22 changed files with 288 additions and 284 deletions.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -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>`
29 changes: 15 additions & 14 deletions docs/development/core/public/kibana-plugin-public.contextsetup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)
);
}
}
Expand All @@ -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)
);
}
Expand Down Expand Up @@ -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);
}
};
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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.

Original file line number Diff line number Diff line change
@@ -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)
);
}
}
}
}

```

Original file line number Diff line number Diff line change
@@ -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`<!-- -->.
Loading

0 comments on commit d453b78

Please sign in to comment.