Embedding Visualizations

There are two different angular directives you can use to insert a visualization in your page. To display an already saved visualization, use the <visualize> directive. To reuse an existing Visualization implementation for a more custom purpose, use the <visualization> 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 <visualize> directive
  • uiState: uiState to pass to <visualize> directive
  • appState: appState to pass to <visualize> directive
  • showSpyPanel: showSpyPanel property to pass to <visualize> directive

<visualize> directive

The <visualize> 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 <visualization> directive.

The simplest way is to just pass saved-id to <visualize>:

<visualize saved-id="'447d2930-9eb2-11e7-a956-5558df96e706'"></visualize>

For the above to work with time based visualizations time picker must be present (enabled) on the page. For scenarios where timepicker is not available time range can be passed in as additional parameter:

<visualize saved-id="'447d2930-9eb2-11e7-a956-5558df96e706'" time-range="{ max: '2017-09-21T21:59:59.999Z', min: '2017-09-18T22:00:00.000Z' }"></visualize>

Once <visualize> is done rendering the element will emit renderComplete event.

When more control is required over the visualization you may prefer to load the saved object yourself and then pass it to <visualize>

<visualize saved-obj='savedVis' app-state='appState' ui-state='uiState' editor-mode='false'></visualize> where

savedVis is an instance of savedVisualization object, which can be retrieved using savedVisualizations service which is explained later in this documentation.

appState is an instance of AppState. <visualize> is expecting two keys defined on AppState:

  • filters which is an instance of searchSource filter object and
  • query which is an instance of searchSource query object

If appState is not provided, <visualize> will not monitor the AppState.

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.

editor-mode defines if <visualize> should render in editor or in view mode.

code example: Showing a saved visualization, without linking to querybar or filterbar.

<div ng-controller="KbnTestController" class="test_vis">
  <visualize saved-obj='savedVis'></visualize>
</div>
import { uiModules } from 'ui/modules';

uiModules.get('kibana')
.controller('KbnTestController', function ($scope, AppState, savedVisualizations) {
  const visId = 'enter_your_vis_id';
  savedVisualizations.get(visId).then(savedVis => $scope.savedObj = savedVis);
});

When <visualize> is ready it will emit ready:vis event on the root scope. When <visualize> is done rendering it will emit renderComplete event on the element.

<visualization> directive

The <visualization> directive takes a visualization configuration and data.

<visualization vis='vis' vis-data='visData' ui-state='uiState' ></visualization> where

vis is an instance of Vis object. The constructor takes 3 parameters:

  • indexPattern <string>: the indexPattern you want to pass to the visualization
  • visConfig <object>: the configuration object
  • uiState <object>: uiState object you want to pass to Vis. If not provided Vis will create its own.

visData is the data object. Each visualization defines a responseHandler, which defines the format of this object.

uiState is an instance of PersistedState. Visualizations use it to keep track of their current state. If not provided <visualization> will create its own (but you won’t be able to check its values)

code example: create single metric visualization

<div ng-controller="KbnTestController" class="test_vis">
  <visualization vis='vis' vis-data='visData'></visualize>
</div>
import { uiModules } from 'ui/modules';

uiModules.get('kibana')
.controller('KbnTestController', function ($scope) {
  const visConfig = {
    type: 'metric'
  };
  $scope.vis = new Vis('.logstash*', visConfig);
  $scope.visData = [{ columns: [{ title: 'Count' }], rows: [[ 1024 ], [ 256 ]] }];
});

<visualization> will trigger renderComplete event on the element once it’s done rendering.