GoodData Dashboard Plugins supply builders a chance to customise GoodData Dashboards in keeping with their particular person wants or enterprise objectives. If you wish to develop your personal plugin, test the tutorial.

This text describes the Dashboard Description plugin, which has already been created. The plugin provides a textual description on prime of the dashboard to which it’s utilized. The outline textual content is loaded from a separate JSON file, so you possibly can 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 may format the outline textual content with markdown and even inject dwell metrics into it. The metrics will respect the worldwide dashboard filters. Because of this the metrics will replace,  each 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: Reside 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. When you use Export Catalog, yow will discover all metrics, attributes, and datasets in exported JSON.

Create Your Dashboard Description Plugin

If you wish to create your personal dashboard description plugin, beneath 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 atmosphere variables

Ensure you have your .env and .env.secrets and techniques recordsdata with right values. After you clone the repository, you will note a .env.secrets and techniques.template file within the dashboard-description-plugin folder. You might want to take away “template” from the filename so as to arrange all the things accurately.

For .env, you will want to outline 4 variables:

# GoodData backend (code title)
BACKEND_TYPE=tiger

# GoodData host
BACKEND_URL=

# GoodData workspace id
WORKSPACE=

# GoodData dashboard id
DASHBOARD_ID=

When you open a GoodData dashboard, yow will discover 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 will want just one variable:

# GoodData API token
TIGER_API_TOKEN=

Examine Create an API token documentation for extra info.

Step 4: Examine dependencies

Make it possible for dependencies within the package deal.json file are aligned with the model of the SDK dashboard element you employ in your mission (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 mission 
  ...
}

Step 5: Construct a manufacturing model

Construct a manufacturing model of the plugin with command npm run build-plugin, or yarn build-plugin. If in case you 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 to your plugin builds. Once you construct your plugin, you’ll have to host it your self in a publicly out there location that helps HTTPS.

Additionally, ensure that 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 info, 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 possibly can 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 subject 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 accommodates 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 legitimate description with the one **MANDATORY** subject, *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 accommodates 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 must 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 not noted, the part might be added with no title.
• grid: OPTIONAL, on objects with width and peak properties. Each predict quantity values. The width must 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 strive dashboard plugins, take a look at our free trial. If you need to debate dashboard plugins, or no matter you will have in your thoughts, attain out to us on our group Slack.