README.md
1# UI Exports
2
3When defining a Plugin, the `uiExports` key can be used to define a map of export types to values that will be used to configure the UI system. A common use for `uiExports` is `uiExports.app`, which defines the configuration of a [`UiApp`][UiApp] and teaches the UI System how to render, bundle and tell the user about an application.
4
5
6## `collectUiExports(pluginSpecs): { [type: string]: any }`
7
8This function produces the object commonly found at `kbnServer.uiExports`. This object is created by calling `collectPluginExports()` with a standard set of export type reducers and defaults for the UI System.
9
10### export type reducers
11
12The [`ui_export_types` module][UiExportTypes] defines the reducer used for each uiExports key (or `type`). The name of every export in [./ui_export_types/index.js][UiExportTypes] is a key that plugins can define in their `uiExports` specification and the value of those exports are reducers that `collectPluginExports()` will call to produce the merged result of all export specs.
13
14### example - UiApps
15
16Plugin authors can define a new UiApp in their plugin specification like so:
17
18```js
19// a single app export
20export default function (kibana) {
21 return new kibana.Plugin({
22 //...
23 uiExports: {
24 app: {
25 // uiApp spec options go here
26 }
27 }
28 })
29}
30
31// apps can also export multiple apps
32export default function (kibana) {
33 return new kibana.Plugin({
34 //...
35 uiExports: {
36 apps: [
37 { /* uiApp spec options */ },
38 { /* second uiApp spec options */ },
39 ]
40 }
41 })
42}
43```
44
45To handle this export type, the [ui_export_types][UiExportTypes] module exports two reducers, one named `app` and the other `apps`.
46
47```js
48export const app = ...
49export const apps = ...
50```
51
52These reducers are defined in [`ui_export_types/ui_apps`][UiAppExportType] and have the exact same definition:
53
54```js
55// `wrap()` produces a reducer by wrapping a base reducer with modifiers.
56// All but the last argument are modifiers that take a reducer and return
57// an alternate reducer to use in it's place.
58//
59// Most wrappers call their target reducer with slightly different
60// arguments. This allows composing standard reducer modifications for
61// reuse, consistency, and easy reference (once you get the hang of it).
62wrap(
63 // calls the next reducer with the `type` set to `uiAppSpecs`, ignoring
64 // the key the plugin author used to define this spec ("app" or "apps"
65 // in this example)
66 alias('uiAppSpecs'),
67
68 // calls the next reducer with the `spec` set to the result of calling
69 // `applySpecDefaults(spec, type, pluginSpec)` which merges some defaults
70 // from the `PluginSpec` because we want uiAppSpecs to be useful individually
71 mapSpec(applySpecDefaults),
72
73 // writes this spec to `acc[type]` (`acc.uiAppSpecs` in this example since
74 // the type was set to `uiAppSpecs` by `alias()`). It does this by concatenating
75 // the current value and the spec into an array. If either item is already
76 // an array its items are added to the result individually. If either item
77 // is undefined it is ignored.
78 //
79 // NOTE: since flatConcatAtType is last it isn't a wrapper, it's
80 // just a normal reducer
81 flatConcatAtType
82)
83```
84
85This reducer format was chosen so that it will be easier to look back at these reducers and see that `app` and `apps` export specs are written to `kbnServer.uiExports.uiAppSpecs`, with defaults applied, in an array.
86
87### defaults
88
89The [`ui_exports/ui_export_defaults`][UiExportDefaults] module defines the default shape of the uiExports object produced by `collectUiExports()`. The defaults generally describe the `uiExports` from the UI System itself, like default visTypes and such.
90
91[UiApp]: ../ui_apps/ui_app.js "UiApp class definition"
92[UiExportDefaults]: ./ui_export_defaults.js "uiExport defaults definition"
93[UiExportTypes]: ./ui_export_types/index.js "Index of default ui_export_types module"
94[UiAppExportType]: ./ui_export_types/ui_apps.js "UiApp extension type definition"
95[PluginSpec]: ../../plugin_discovery/plugin_spec/plugin_spec.js "PluginSpec class definition"
96[PluginDiscovery]: '../../plugin_discovery' "plugin_discovery module"