@kong-ui-public/dashboard-renderer

Render Analytics charts on a page from a JSON definition.

• Requirements
• Usage
  • Props
  • Example

Requirements

• vue must be initialized in the host application
• A plugin providing an AnalyticsBridge must be installed in the root of the application.
  • This plugin must provide the necessary methods to adhere to the AnalyticsBridge interface defined in @kong-ui-public/analytics-utilities.
  • The plugin's query method is in charge of passing the query to the correct API for the host app's environment.
  • See the sandbox plugin sandbox-query-provider.ts for an example that simply returns static data rather than consuming an API.
• The host application must supply peer dependencies for:
  • @kong-ui-public/analytics-chart
  • @kong-ui-public/analytics-utilities
  • @kong-ui-public/analytics-metric-provider
  • @kong-ui-public/i18n
  • @kong/kongponents
  • swrv
  • vue

Usage

Props

This component only takes two properties:

• context : The time range that the dashboard should query and any additional filters that should be applied.
• config : The dashboard config and layout.

For context filters and timeSpec see here.

If a timeSpec is not provided in the context object, the renderer will determine a default, which is currently 7 days.

Example

<DashboardRenderer
  :context="context"
  :config="config"
/>

with the following data:

import type { DashboardRendererContext, DashboardConfig } from '@kong-ui-public/dashboard-renderer'
import { DashboardRenderer, ChartTypes } from '@kong-ui-public/dashboard-renderer'

const context: DashboardRendererContext = {
  filters: [],
  timeSpec: {
    type: 'relative',
    time_range: '15M',
  },
}

const config: DashboardConfig = {
  // 4 x 1 grid
  gridSize: {
    cols: 4,
    rows: 1,
  },
  tiles: [
    {
      definition: {
        chart: {
          type: 'horizontal_bar',
        },
        // Request count by route
        query: {
          metrics: ['request_count'],
          dimensions: ['route']
        },
      },
      layout: {
        // Position at column 0, row 0
        position: {
          col: 0,
          row: 0,
        },
        // Spans 2 columns and 1 rows
        size: {
          col: 2,
          row: 1,
        }
      }
    },
    {
      definition: {
        chart: {
          type: 'top_n',
          chartTitle: 'Top N Table',
          description: 'Table description',
        },
        // Top 5 routes by request_count
        query: {
          metrics: ['request_count'],
          dimensions: ['route'],
          limit: 5,
        },
      },
      layout: {
        // Position at column 2, row 0
        position: {
          col: 2,
          row: 0,
        },
        // Spans 2 columns and 1 rows
        size: {
          col: 2,
          row: 1,
        }
      }
    },
  ],
}

Slotted content

<DashboardRenderer
  :context="context"
  :config="config"
>
  <!-- use the `id` set in the tile config for the slot name -->
  <template #slot-1>
    <div>
      <h3>Custom Slot</h3>
      <p>This is a slotted tile</p>
    </div>
  </template>
</DashboardRenderer>

import type { DashboardRendererContext, DashboardConfig } from '@kong-ui-public/dashboard-renderer'
import { DashboardRenderer, ChartTypes } from '@kong-ui-public/dashboard-renderer'

const context: DashboardRendererContext = {
  filters: [],
  timeSpec: {
    type: 'relative',
    time_range: '15M',
  },
}

const config: DashboardConfig = {
  // 4 x 1 grid
  gridSize: {
    cols: 4,
    rows: 1,
  },
  tiles: [
    {
      // Line chart
      definition: {
        chart: {
          type: 'timeseries_line',
        },
        // requests by status code over time
        query: {
          metrics: ['request_count'],
          dimensions: ['status_code', 'time']
        },
      },
      layout: {
        // Position at column 0, row 0
        position: {
          col: 0,
          row: 0,
        },
        // Spans 2 columns and 1 rows
        size: {
          col: 2,
          row: 1,
        }
      }
    },
    {
      // Slottable tile
      definition: {
        chart: {
          type: 'slottable',
          id: 'slot-1' // slot name
        },
        query: {},
      },
      layout: {
        // Position at column 2, row 0
        position: {
          col: 2,
          row: 0,
        },
        // Spans 2 columns and 1 rows
        size: {
          col: 2,
          row: 1,
        }
      }
    },
  ],
}

Auto-fit row content

This example will create a dynamically-sized row that fits to its content rather than being fixed at the configured row height. Note that this works because each chart is only rendered in 1 row; if a chart has fitToContent and layout.size.rows > 1, the fitToContent setting will be ignored.

Rendering AnalyticsChart components (e.g., horizontal bar, vertical bar, timeseries charts) with dynamic row heights may lead to undefined behavior. This option is best used with non-canvas charts (e.g., TopN charts).

import type { DashboardRendererContext, DashboardConfig } from '@kong-ui-public/dashboard-renderer'
import { DashboardRenderer, ChartTypes } from '@kong-ui-public/dashboard-renderer'

const context: DashboardRendererContext = {
  filters: [],
  timeSpec: {
    type: 'relative',
    time_range: '15M',
  },
}

const config: DashboardConfig = {
  // 4 x 1 grid
  gridSize: {
    cols: 4,
    rows: 1,
  },
  tiles: [
    {
      definition: {
        chart: {
          type: 'top_n',
          chartTitle: 'Top N chart of mock data',
          description: 'Description'
        },
        query: {},
      },
      layout: {
        position: {
          col: 0,
          row: 0,
        },
        size: {
          cols: 3,
          rows: 1,
          fitToContent: true,
        },
      },
    },
    {
      definition: {
        chart: {
          type: 'top_n',
          chartTitle: 'Top N chart of mock data',
          description: 'Description',
        },
        query: {},
      },
      layout: {
        position: {
          col: 3,
          row: 0,
        },
        size: {
          cols: 3,
          rows: 1,
          fitToContent: true,
        },
      },
    },
  ],
}