カスタマイズ可能なダッシュボード
GitLab 15.5からExperimentとして導入されました。
カスタマイズ可能なダッシュボードは設定ベースのダッシュボード構造を提供し、GitLabやユーザーによって作成されたダッシュボードの設定をレンダリングしたり変更したりするために使用されます。
このダッシュボード構造は、ユーザーの設定ファイルをリポジトリに保存してバージョン管理する手段を提供しません。この機能はカスタマイズ可能なダッシュボードコンポーネントを使用するAnalyticsダッシュボードが提供します。
カスタマイズ可能なダッシュボードは、Premium および Ultimate サブスクリプション向けです。
概要
カスタマイズ可能なダッシュボードは、3つの論理コンポーネントに分解できます：
- ダッシュボード
- パネル
- ビジュアライゼーション
ダッシュボードはレンダリングするパネルのリストで構成され、各パネルは 1 つのビジュアライゼーションを参照し、1 つのビジュアライゼーションを複数のパネルで共有することができます。
典型的なダッシュボードの構造は次のようになります：
dashboard
├── panelA
│ └── visualizationX
├── panelB
│ └── visualizationY
├── panelC
│ └── visualizationY
使用方法
カスタマイズ可能なダッシュボードを使用するには
- ダッシュボード用に新しいVueコンポーネントを作成します。
- 視覚化設定を作成します。
- ダッシュボード設定を作成します。
-
CustomizableDashboardのインスタンスをレンダリングし、ダッシュボード設定を渡します。
視覚化の設定
各ビジュアライゼーションは、データ・ソースから取得したクエリ結果をグラフィカルに表現したものです。
// visualizations.js
export const pageViewsOverTime = {
// The name of the Vue component used to render the query.
type: 'LineChart',
// Chart options defined by the charting library being used by the panel.
options: {
xAxis: { name: __('Time'), type: 'time' },
yAxis: { name: __('Counts'), type: 'time' },
},
// The data to query
data: {
// The data source to query. Here it is Product Analytics.
type: 'cube_analytics',
// The query to run on the data source. Here in Cube.js format.
query: {
dimensions: [],
filters: [
{
member: 'SnowplowTrackedEvents.event',
operator: 'equals',
values: ['page_view']
}
],
measures: ['SnowplowTrackedEvents.pageViewsCount'],
timeDimensions: [
{
dimension: 'SnowplowTrackedEvents.derivedTstamp',
granularity: 'day',
},
],
limit: 100,
timezone: 'UTC',
},
},
};
新しい可視化レンダリングタイプの追加
新しい視覚化レンダリング タイプを追加します：
-
dataとoptionsプロパティを受け付ける新しい Vue コンポーネントを作成します。例としてline_chart.vueを参照してください。 -
panel_base.vueの条件付きインポートのリストにコンポーネントを追加します。
新しい可視化データソースの追加
新しいデータ・ソースを追加するには
-
fetchメソッドをエクスポートする新しい JavaScript モジュールを作成します。例としてcube_analytics.jsを参照してください。 -
data_sources/index.jsのエクスポートリストにあなたのモジュールを追加してください。
すべてのパネルが同じ日付範囲のデータを表示するように、データソースはフィルタを尊重しなければなりません。
ダッシュボードの設定
ダッシュボードの設定例を示します：
// constants.js
import { pageViewsOverTime } from './visualizations';
export const dashboard = {
slug: 'my_dashboard', // Used to set the URL path for the dashboard.
title: 'My dashboard title', // The title to display.
// Each dashboard consists of an array of panels to display.
panels: [
{
id: 1,
title: 'Page views over time', // The panel title to display.
// The visualization configuration. This can be shared by many panels.
visualization: pageViewsOverTime,
// Gridstack settings based upon https://github.com/gridstack/gridstack.js/tree/master/doc#item-options.
// All values are grid row/column numbers up to 12.
// We use the default 12 column grid https://github.com/gridstack/gridstack.js#change-grid-columns.
gridAttributes: {
yPos: 1,
xPos: 0,
width: 6,
height: 5,
},
// Optional overrides for the values in `visualization.data.query`.
// Here we override the Cube.js query to get page views per week instead of days.
queryOverrides: {
timeDimensions: {
dimension: 'SnowplowTrackedEvents.derivedTstamp',
granularity: 'week',
},
},
},
],
};
コンポーネントの使用
カスタマイズ可能なダッシュボードをレンダリングするコンポーネントの例を示します：
<script>
import CustomizableDashboard from 'ee/vue_shared/components/customizable_dashboard/customizable_dashboard.vue';
import { dashboard } from './constants';
export default {
name: 'AnalyticsDashboard',
components: {
CustomizableDashboard,
},
data() {
return {
// We keep the original (default) dashboard object to track changes.
dashboard: {
...dashboard,
default: { ...dashboard, }
},
// Optional dashboard filters. Currently the only availble filter is date range.
defaultFilters: {
dateRangeOption: 'last_7_days' // 'custom', 'today', 'last_7_days', 'last_30_days'
endDate: new Date(2023, 06, 14),
startDate: new Date(2023, 06, 7),
},
// Set to true to sync the filter object with the URL query string.
syncUrlFilters: true,
// Set to true to show the date range filter.
showDateRangeFilter: true,
// The maximum size of the date range allowed in days. 0 for unlimited.
dateRangeLimit: 0,
};
},
};
</script>
<template>
<customizable-dashboard
:initial-dashboard="dashboard"
:default-filters="defaultFilters"
:sync-url-filters="syncUrlFilters"
:show-date-range-filter="showDateRangeFilter"
:date-range-limit="dateRangeLimit"
/>
</template>
ダッシュボードデザイナー
GitLab 16.1 で
combined_analytics_dashboards_editorというフラグで導入されました。デフォルトでは無効になっています。
ダッシュボードデザイナーは、ユーザーがユーザー定義のダッシュボードのパネルを変更したり、新しいパネルを追加したりするためのグラフィカルインターフェースを提供します。GitLabのハードコードされたダッシュボードでは利用できません。
ダッシュボードデザイナーは初期の実験ステージであり、変更される可能性があります。
<script>
import { s__ } from '~/locale';
export const I18N_MY_NEW_CATEGORY = s__('Namespace|My data source');
export default {
name: 'AnalyticsDashboard',
data() {
return {
...,
// Set to true to render the dashboard saving state.
isSaving: false,
// A list of availble visualizations categorized by feature.
availableVisualizations: {
// The visualization category title to display.
[I18N_MY_NEW_CATEGORY]: {
// Set to true when asynchronously loading the visualization IDs
loading: false,
// List of availble visualization IDs for the user to add to the dashboard.
visualizationIds: [
'page_views_over_time',
'events_over_time',
],
},
}
};
},
methods: {
/**
* Event handler for when a user saves changes made to the current dashboard.
* @param {String} dashboardId The current dashboard ID.
* @param {String} newDashboardObject The newly modified dashboard object.
*/
saveDashboard(dashboardId, newDashboardObject) {
// Save changes and modify `this.dashboard`.
},
/**
* Event handler for when a user adds a visualization in a new panel.
* @param {String} visualizationId The ID (usually filename) of the visualization.
* @param {String} visualizationSource The source to get the new visualization config.
*/
addNewPanel(visualizationId, visualizationSource) {
// Load the visualization and push a new panel onto `this.dashboard.panels`.
},
},
}
</script>
<template>
<customizable-dashboard
...
:available-visualizations="availableVisualizations"
:is-saving="isSaving"
@save="handleSave"
@add-panel="handleAddPanel"
/>
</template>