GoodData Dashboard plugins provide builders a chance to customise GoodData Dashboards in keeping with their particular person wants or enterprise targets. If you wish to develop your personal plugin, verify the tutorial.

Notice: within the second article on this sequence protecting our Gauge Chart plugin? Learn it right here.

This text describes the Dashboard Description plugin, which has already been created. The plugin provides a textual description on high of the dashboard to which it’s utilized. The outline textual content is loaded from a separate JSON file, so you’ll be able to reuse the identical plugin throughout totally different dashboards and easily present a distinct URL to the JSON file when linking the plugin to the dashboard.

You’ll be able to format the outline textual content with markdown and even inject dwell metrics into it. The metrics will respect the worldwide dashboard filters. Which means that the metrics will replace,  every time a filter is modified. To inject a metric, merely use inline code with a selected syntax: metric:and outline the corresponding metric object reference in a metrics part of the JSON configuration.

{
    "liveMetrics": {
        "sectionIndex": 0,
        "sectionTitle": "Description pattern: Dwell metrics pattern",
        "description": "*Complete Gross sales are `metric:total_sales`", <-- inline code with metric
        "metrics": { <-- metrics part
            "total_sales": {
                "identifier": "totalsales"
            }
        },
        "dateDataSet": {
            "identifier": "gross sales.dataset.dt"
        }
    }
}

See the entire instance of the configuration in texts.json file. For those who use Export Catalog, you could find all metrics, attributes, and datasets in exported JSON.

Create Your Dashboard Description Plugin

If you wish to create your personal dashboard description plugin, under are the steps on how you are able to do it.

Step 1: Clone dashboard-plugin-examples repository

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

Step 2: Navigate to dashboard-description-plugin

cd dashboard-description-plugin

Step 3: Set surroundings variables

Be sure you have your .env and .env.secrets and techniques information with appropriate values. After you clone the repository, you will note a .env.secrets and techniques.template file within the dashboard-description-plugin folder. It’s good to take away “template” from the filename in an effort to arrange every thing accurately.

For .env, you’ll need to outline 4 variables:

# GoodData backend (code identify)
BACKEND_TYPE=tiger

# GoodData host
BACKEND_URL=

# GoodData workspace id
WORKSPACE=

# GoodData dashboard id
DASHBOARD_ID=

For those who open a GoodData dashboard, you could find the BACKEND_URL, WORKSPACE_ID, and the  DASHBOARD_ID within the URL:

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

For .env.secrets and techniques, you’ll need just one variable:

# GoodData API token
TIGER_API_TOKEN=

Verify Create an API token documentation for extra data.

Step 4: Verify dependencies

Be sure that dependencies within the package deal.json file are aligned with the model of the SDK dashboard element you employ in your venture (in case you are embedding the dashboards with the GoodData SDK).

{
  ...
  "@gooddata/sdk-ui-dashboard": "^9.2.0" <-- should match within the plugin and your venture 
  ...
}

Step 5: Construct a manufacturing model

Construct a manufacturing model of the plugin with command npm run build-plugin, or yarn build-plugin. You probably have this plugin already constructed, first delete the dist folder.

Step 6: Add the constructed plugin

Add constructed plugin to your internet hosting. GoodData doesn’t present internet hosting on your plugin builds. Whenever you construct your plugin, you’ll have to host it your self in a publicly accessible location that helps HTTPS.

Additionally, make certain the internet hosting of your plugin is included within the allowed plugin hosts by CSP Coverage (documentation).

Step 7: Create plugin metadata object

Create a plugin metadata object with npm run add-plugin or yarn add-plugin instructions. For extra data, run the npm run add-plugin –assist, or yarn add-plugin –help command.

Copy the plugin object-id famous within the console output.

Step 8: Hyperlink the plugin to the dashboard

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

It will open the textual content editor the place you’ll be able to paste a Configuration JSON file with a hyperlink to a file with a Texts JSON file, and optionally IDs and positions of texts if you wish to present solely sure texts on a selected dashboard.

Configuration JSON file

Configuration JSON is an object that’s handed to the plugin as a parameter when linking the plugin with a dashboard.

{
    url: "https://www.myHosting.com/texts.json",
    texts: {
        description1: 0,
        description3: 2,
    }
}

• url: MANDATORY, a hyperlink to publicly accessible JSON file with texts definition(s).
• texts: OPTIONAL, key-value pairs of textual content IDs (keys in Texts JSON) with a quantity describing part index the place so as to add the part with textual content on the dashboard. If the texts area is omitted, all texts from the texts.json might be proven within the dashboard.

texts.json file

The texts.json is a publicly accessible file with textual content definitions. It comprises key-value pairs with textIDs as keys and outline textual content definitions as values.

{
    "description1": {
        "description": "Textual content with the dwell *metric*: `metric:my_metric_1`",
        "metrics": {
            "my_metric_1": {
                "identifier": "mymetric1"
            }
        },
        "sectionIndex": 1,
        "sectionTitle": "Dashboard description",
        "grid": {
            "width": 6,
            "peak": 2
        },
        "wrap": false
    },
    "description2": {
        "description": "A sound description with the one **MANDATORY** area, *description*"
    },
    "description3": {
        "description": "One other description with the **OPTIONAL** Part title",
        "sectionTitle": "Description 3 part title"
    }
}

The texts.json is a publicly accessible file with textual content definitions. It comprises key-value pairs with textIDs as keys and outline textual content definitions as values.

• description: MANDATORY, the personal textual content of the outline within the markdown format.
• metrics: OPTIONAL, key-value pairs of metrics used within the description textual content. The worth ought to be an object reference to the metric.
• dateDataSet: OPTIONAL, supplied when utilizing dwell metrics. It’s wanted in order that dwell metrics would respect the date filters of your dashboard.
• sectionIndex: OPTIONAL, defaults to 0. Every description will add a brand new part to the dashboard. That is the listed place(ranging from 0) of the part throughout the dashboard.
• sectionTitle: OPTIONAL, the title of the part with the outline. If unnoticed, the part might be added with out a title.
• grid: OPTIONAL, on objects with width and peak properties. Each expect quantity values. The width ought to be a quantity between 1 and 12 and represents the width of the textual content ingrid columns. The peak defines the peak of the outline in grid rows. Defaults to { width: 12, peak: 1 }.

As soon as the plugin is linked to the dashboard, it’s going to develop into seen in your dashboard, and you can begin utilizing it!

Give It a Attempt

If you wish to attempt dashboard plugins, try our free trial. If you need to debate dashboard plugins, or no matter you’ve in your thoughts, attain out to us on our neighborhood Slack.