Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[skip-ci] Update migration guide to add rendering service example #54744

Merged
merged 4 commits into from
Jan 21, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/core/MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -1193,10 +1193,11 @@ In server code, `core` can be accessed from either `server.newPlatform` or `kbnS
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `server.config()` | [`initializerContext.config.create()`](/docs/development/core/server/kibana-plugin-server.plugininitializercontext.config.md) | Must also define schema. See _[how to configure plugin](#configure-plugin)_ |
| `server.route` | [`core.http.createRouter`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.createrouter.md) | [Examples](./MIGRATION_EXAMPLES.md#route-registration) |
| `server.renderApp()` / `server.renderAppWithDefaultConfig()` | [`context.rendering.render()`](/docs/development/core/server/kibana-plugin-server.iscopedrenderingclient.render.md) | [Examples](./MIGRATION_EXAMPLES.md#render-html-content) |
| `request.getBasePath()` | [`core.http.basePath.get`](/docs/development/core/server/kibana-plugin-server.httpservicesetup.basepath.md) | |
| `server.plugins.elasticsearch.getCluster('data')` | [`context.elasticsearch.dataClient`](/docs/development/core/server/kibana-plugin-server.iscopedclusterclient.md) | |
| `server.plugins.elasticsearch.getCluster('admin')` | [`context.elasticsearch.adminClient`](/docs/development/core/server/kibana-plugin-server.iscopedclusterclient.md) | |
| `server.plugins.elasticsearch.createCluster(...)` | [`core.elasticsearch.createClient`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md) | |
| `server.plugins.elasticsearch.createCluster(...)` | [`core.elasticsearch.createClient`](/docs/development/core/server/kibana-plugin-server.elasticsearchservicesetup.createclient.md) | |
| `server.savedObjects.setScopedSavedObjectsClientFactory` | [`core.savedObjects.setClientFactory`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.setclientfactory.md) | |
| `server.savedObjects.addScopedSavedObjectsClientWrapperFactory` | [`core.savedObjects.addClientWrapper`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.addclientwrapper.md) | |
| `server.savedObjects.getSavedObjectsRepository` | [`core.savedObjects.createInternalRepository`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.createinternalrepository.md) [`core.savedObjects.createScopedRepository`](/docs/development/core/server/kibana-plugin-server.savedobjectsservicesetup.createscopedrepository.md) | |
Expand Down
85 changes: 83 additions & 2 deletions src/core/MIGRATION_EXAMPLES.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ APIs to their New Platform equivalents.
- [Accessing Services](#accessing-services)
- [Chrome](#chrome)
- [Updating an application navlink](#updating-application-navlink)

- [Chromeless Applications](#chromeless-applications)
- [Render HTML Content](#render-html-content)

## Configuration

### Declaring config schema
Expand Down Expand Up @@ -518,4 +520,83 @@ export class MyPlugin implements Plugin {
},
});
}
```
```

## Chromeless Applications

In Kibana, a "chromeless" application is one where the primary Kibana UI components
such as header or navigation can be hidden. In the legacy platform these were referred to
as "hidden" applications, and were set via the `hidden` property in a Kibana plugin.
Chromeless applications are also not displayed in the left navbar.

To mark an application as chromeless, specify `chromeless: false` when registering your application
to hide the chrome UI when the application is mounted:

```ts
application.register({
id: 'chromeless',
chromeless: true,
async mount(context, params) {
/* ... */
},
});
```

If you wish to render your application at a route that does not follow the `/app/${appId}` pattern,
this can be done via the `appRoute` property. Doing this currently requires you to register a server
route where you can return a bootstrapped HTML page for your application bundle. Instructions on
registering this server route is covered in the next section: [Render HTML Content](#render-html-content).

```ts
application.register({
id: 'chromeless',
appRoute: '/chromeless',
chromeless: true,
async mount(context, params) {
/* ... */
},
});
```

## Render HTML Content

You can return a blank HTML page bootstrapped with the core application bundle from an HTTP route handler
via the `rendering` context. You may wish to do this if you are rendering a chromeless application with a
custom application route or have other custom rendering needs.

```ts
router.get(
{ path: '/chromeless', validate: false },
(context, request, response) => {
const { http, rendering } = context.core;

return response.ok({
body: await rendering.render(), // generates an HTML document
headers: {
'content-security-policy': http.csp.header,
},
});
}
);
```

You can also specify to exclude user data from the bundle metadata. User data
comprises all UI Settings that are *user provided*, then injected into the page.
You may wish to exclude fetching this data if not authorized or to slim the page
size.

```ts
router.get(
{ path: '/', validate: false },
(context, request, response) => {
const { http, rendering } = context.core;

return response.ok({
body: await rendering.render({ includeUserSettings: false }),
headers: {
'content-security-policy': http.csp.header,
},
});
}
);
```