GoodData Plugins #2: Gauge Chart

GoodData Dashboard Plugins allow developers to customize GoodData Dashboards according to their individual needs or business goals. If you want to develop your own plugin, check out this tutorial.

Note: Missed the first article in this series covering our Dashboard Description plugin? Read it here.Also, check the next article from the dashboard plugins series, which focuses on Insight Groups.

This article describes the Gauge Chart plugin. A Gauge Chart is a type of chart that utilizes a radial scale to present data in the form of a dial. Typically, the scale in a Gauge Chart is divided into segments to provide a more detailed representation of the scale. These segments can be color-coded to quickly indicate whether the given value falls below or exceeds the expected/standard range.

If you want to use the plugin (Gauge Chart) on your GoodData dashboard, it means that the plugin will affect all Bullet charts in the following way:

• Each Bullet Chart must contain exactly one primary metric and one target metric, with the comparative metric and 'view by' attribute left empty.
• These visualizations are then replaced by the gauge component.
• The maximum value of the Gauge Chart corresponds to the target value of the original Bullet Chart.
• The needle on the Gauge Chart indicates the primary metric of the original Bullet Chart.
• The minimum value in the Gauge chart component is always set to 0.

Create Your Gauge Chart Plugin

If you want to create your own Gauge Chart plugin, below are the steps to do it.

Step 1: Clone dashboard-plugin-examples repository

git clone https://github.com/gooddata/gooddata-dashboard-plugins.git

Step 2: Navigate to gauge_chart_plugin

cd gauge_chart_plugin

Step 3: Set environment variables

Make sure you have your .env and .env.secrets files with the correct values. After you clone the repository, you will see a .env.secrets.template file in the gauge_chart_plugin folder. You need to remove “template” from the filename to set up everything correctly.

For .env, you will need to define four variables:

# GoodData backend (code name)
BACKEND_TYPE=tiger

# GoodData host
BACKEND_URL=

# GoodData workspace id
WORKSPACE=

# GoodData dashboard id
DASHBOARD_ID=

If you open a GoodData dashboard, you can find the BACKEND_URL, WORKSPACE_ID, and the DASHBOARD_ID in the URL like this:

https://<BACKEND_URL>/dashboards/#/workspace/<WORKSPACE_ID>/dashboard/<DASHBOARD_ID>

For .env.secrets, you will need only one variable:

# GoodData API token
TIGER_API_TOKEN=

Check Create an API token documentation for more information.

Step 4: Check dependencies

Make sure that dependencies in the package.json file are aligned with the version of the SDK dashboard component you use in your project (if you are embedding the dashboards with the GoodData SDK).

{

  ...

  "@gooddata/sdk-ui-dashboard": "^9.2.0" <-- must match in the plugin and your project 

  ...

}

Step 5: Build a production version

Build a production version of the plugin using the command npm run build-plugin, or yarn build-plugin. If you have already built this plugin, first delete the dist folder.

Step 6: Upload the built plugin

Upload the built plugin to your hosting. GoodData does not provide hosting for your plugin builds. When you build your plugin, you have to host it yourself in a publicly available location that supports HTTPS.

Also, make sure the hosting of your plugin is included in the allowed plugin hosts by CSP Policy (documentation).

Step 7: Create plugin metadata object

Create a plugin metadata object using npm run add-plugin or yarn add-plugin command. For more information, run the npm run add-plugin –help, or yarn add-plugin --help command.

Copy the plugin object-id noted in the console output for the next step.

Step 8: Link the plugin to the dashboard

Run npm run link-plugin ----with-parameters, or yarn link-plugin ----with-parameterscommand.

This will open the text editor where you paste the following string:

{
    "prefixes":"gauge",
    "showLabels":false, 
    "format":"%"
}

• prefixes: you can specify naming prefixes you want the plugin to apply, separated by spaces. If not specified, the default prefix 'gauge' is used.
• format: the format parameter accepts '#' to show values in numeral representation or '%' to display the percentage of the value. If an empty or invalid value is entered, the percentage format is used.
• showLabels: indicates whether to display the minimum and maximum value labels. If not specified, labels are hidden.

Once the plugin is linked to the dashboard, it becomes visible, and you can start using it!

What's Next?

If you want to try dashboard plugins, check out our free trial. If you would like to discuss dashboard plugins, or whatever you have on your mind, reach out to us on our community Slack.