[[development-embedding-visualizations]] === Embedding Visualizations <<<<<<< HEAD There are two different angular directives you can use to insert a visualization in your page. To display an already saved visualization, use the `` directive. To reuse an existing Visualization implementation for a more custom purpose, use the `` directive instead. ==== VisualizeLoader The `VisualizeLoader` class i the easiest way to embed a visualization into your plugin. It exposes two methods: - `getVisualizationList()`: which returns promise which gets resolved with list of saved visualizations - `embedVisualizationWithId(container, savedId, params)`: which embeds visualization by id - `embedVisualizationWithSavedObject(container, savedObject, params)`: which embeds visualization from saved object `container` should be a dom element to which visualization should be embedded `params` is a parameter object where the following properties can be defined: - `timeRange`: time range to pass to `` directive - `uiState`: uiState to pass to `` directive - `appState`: appState to pass to `` directive - `showSpyPanel`: showSpyPanel property to pass to `` directive ======= There are two different methods you can use to insert a visualization in your page. >>>>>>> e5d2ff821... Refactor and improve Visualize Loader (#15157) To display an already saved visualization, use the `VisualizeLoader`. To reuse an existing visualization implementation for a more custom purpose, use the Angular `` directive instead. <<<<<<< HEAD ==== `` directive The `` directive takes care of loading data, parsing data, rendering the editor (if the Visualization is in edit mode) and rendering the visualization. The directive takes a savedVis object for its configuration. It is the easiest way to add visualization to your page under the assumption that the visualization you are trying to display is saved in kibana. If that is not the case, take a look at using `` directive. The simplest way is to just pass `saved-id` to ``: `` ======= ==== VisualizeLoader >>>>>>> e5d2ff821... Refactor and improve Visualize Loader (#15157) The `VisualizeLoader` class is the easiest way to embed a visualization into your plugin. It will take care of loading the data and rendering the visualization. <<<<<<< HEAD `` ======= To get an instance of the loader, do the following: >>>>>>> e5d2ff821... Refactor and improve Visualize Loader (#15157) ["source","js"] ----------- import { getVisualizeLoader } from 'ui/visualize/loader'; getVisualizeLoader().then((loader) => { // You now have access to the loader }); ----------- The loader exposes the following methods: - `getVisualizationList()`: which returns promise which gets resolved with a list of saved visualizations - `embedVisualizationWithId(container, savedId, params)`: which embeds visualization by id - `embedVisualizationWithSavedObject(container, savedObject, params)`: which embeds visualization from saved object Depending on which embed method you are using, you either pass in the id of the saved object for the visualization, or a `savedObject`, that you can retrieve via the `savedVisualizations` Angular service by its id. The `savedObject` give you access to the filter and query logic and allows you to attach listeners to the visualizations. For a more complex use-case you usually want to use that method. `container` should be a DOM element (jQuery wrapped or regular DOM element) into which the visualization should be embedded `params` is a parameter object specifying several parameters, that influence rendering. You will find a detailed description of all the parameters in the inline docs in the {repo}blob/{branch}/src/ui/public/visualize/loader/loader.js[loader source code]. <<<<<<< HEAD `uiState` should be an instance of `PersistedState`. if not provided visualize will generate one, but you will have no access to it. It is used to store viewer specific information like whether the legend is toggled on or off. ======= Both methods return an `EmbeddedVisualizeHandler`, that gives you some access to the visualization. The `embedVisualizationWithSavedObject` method will return the handler immediately from the method call, whereas the `embedVisualizationWithId` will return a promise, that resolves with the handler, as soon as the `id` could be found. It will reject, if the `id` is invalid. >>>>>>> e5d2ff821... Refactor and improve Visualize Loader (#15157) The returned `EmbeddedVisualizeHandler` itself has the following methods and properties: - `destroy()`: destroys the underlying Angualr scope of the visualization - `getElement()`: a reference to the jQuery wrapped DOM element, that renders the visualization - `whenFirstRenderComplete()`: will return a promise, that resolves as soon as the visualization has finished rendering for the first time - `addRenderCompleteListener(listener)`: will register a listener to be called whenever a rendering of this visualization finished (not just the first one) - `removeRenderCompleteListener(listener)`: removes an event listener from the handler again You can find the detailed `EmbeddedVisualizeHandler` documentation in its {repo}blob/{branch}/src/ui/public/visualize/loader/embedded_visualize_handler.js[source code]. <<<<<<< HEAD When is ready it will emit `ready:vis` event on the root scope. When is done rendering it will emit `renderComplete` event on the element. ======= We recommend *not* to use the internal `` Angular directive directly. >>>>>>> e5d2ff821... Refactor and improve Visualize Loader (#15157) ==== `` directive The `` directive takes a visualization configuration and data. It should be used, if you don't want to render a saved visualization, but specify the config and data directly. `` where `vis` is an instance of `Vis` object. The constructor takes 3 parameters: - `indexPattern` : the indexPattern you want to pass to the visualization - `visConfig`