[skip-ci] Update migration guide to add rendering service example (#5…

…4744) (#55466) * Update migration guide to add rendering service example * Address review nits * Address nits * Add chromeless apps to TOC
elastic · Jan 21, 2020 · 09c2b8e · 09c2b8e
1 parent 2fcac07
commit 09c2b8e
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 3 deletions.
diff --git a/src/core/MIGRATION.md b/src/core/MIGRATION.md
@@ -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) |                                                                             |

diff --git a/src/core/MIGRATION_EXAMPLES.md b/src/core/MIGRATION_EXAMPLES.md
@@ -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
@@ -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,
+      },
+    });
+  }
+);
+```