Dashboard Plugins
Dashboard plugins allow developers to create and integrate custom code into the Dashboard component. With the plugins, you as a developer can customize and enhance the default dashboard experience available to the dashboard consumers.
The plugins are an essential part of the GoodData dashboard stack.
Important change in the dashboard plugins since version 9.5.0:
Before v9.5.0, all dashboard plugins were locked to a set Dashboard component and some other GoodData.UI packages that were used to build the plugin. From v9.5.0 onwards, all plugins will always run with the latest version of these packages, which will be injected into the plugin at runtime. Version locking is now deprecated and no longer supported. We recommend you to upgrade as soon as possible.
What a dashboard plugin is
A dashboard plugin is an object that implements a contract defined by GoodData and that is built and bundled in a way supported by the GoodData.UI dashboard loader.
The dashboard plugins are registered into a workspace and from then on can be used on any number of dashboards. To facilitate plugin reuse across dashboards, you can parameterize the link between the dashboard and the plugin.
You can find plugin examples in GoodData Dashboard Plugin examples gallery.
Plugin contract and lifecycle
The plugin contract is described by an interface defined in the @gooddata/sdk-ui-dashboard
package. You can see the code
here.
The contract is versioned to accommodate for potential future breaking changes. Currently, the only supported version of the contract is v1, which we intend to enhance in a backward-compatible fashion.
The contract is fairly straightforward and specifies the things that you as an author have to provide or implement:
- The properties through which you provide metadata about the plugin
- The
register
function that will be called during dashboard initialization and before the Dashboard component is mounted. This is where your code can register customizations and enhancements. - (Optional) The
onPluginLoaded
lifecycle function that will be called as the plugin assets are loaded and before dashboard initialization - (Optional) The
onPluginUnload
lifecycle function that will be called when the Dashboard component enhanced by your plugin is unmounted
Build and bundling
The dashboard loader relies on the Webpack Module Federation feature to load and link plugins at runtime.
A plugin must be built into a bundle that is configured to inherit these dependencies from the context into which it is loaded:
- All
@gooddata
dependencies react
andreact-dom
Apart form this, the plugin can depend on other packages and include custom assets as it sees fit.
Building the plugin correctly is essential to have the plugin load successfully. The plugin template that is part of GoodData.UI ships with the default Webpack config that you should use as a starting point.
Runtime guarantees and implications
Lifecycle
Every time your plugin is loaded to be used on a dashboard, it will be instantiated exactly once. If implemented, your
onPluginLoaded
, register
and onPluginUnload
will be called once every time the dashboard that links to your
plugin is loaded.
Dependencies
All GoodData.UI dependencies are injected into the dashboard plugin at runtime with their latest versions. This ensures that all new features become available to the dashboard associated with the plugin as soon as we release them. However, this approach has certain consequences. In particular, there may be instances where a new dashboard component feature, upon rollout, is incompatible with your deployed dashboard plugin. This incompatibility can occur even if there is no breaking change at the API level. Since dashboard plugins offer extensive capabilities for customization, we cannot control the code of deployed plugins. To minimize these issues, please adhere to the following recommendations.
Recommendations
- Use only the public dashboard plugins API and GoodData.UI interfaces. Anything marked as alpha, beta, or internal within the plugin code should be used at your own risk. If you are missing an API for your particular use case or need something not yet marked as stable, please get in touch with us, and we may consider updating or extending it.
- Do not manipulate the CSS or DOM structure of the dashboard. Instead, stick to the theming guidelines.
- Create smaller, focused plugins. Avoid large, complicated plugins that drastically change the dashboard’s behavior and look.
- For more complex changes, consider using better-suited approaches, such as using the standalone dashboard component or building your custom dashboard
Maintenance
Since dashboard plugins are primarily integrated with our ever-evolving SaaS platform (GoodData Platform or GoodData Cloud), there are occasions when introducing breaking changes is necessary.
When this occurs, a grace period of approximately six months will be provided, allowing for the safe migration of your plugins. However, after this time frame, the dashboard will default to running with the latest version, and reverting to older versions will not be possible. Any plugins that have not been migrated to the new API version will not load once the grace period concludes.
Capabilities
The dashboard customization and enhancement capabilities are exposed to your plugin code via customization APIs. An
instance of the API will be provided to your code at the time of the plugin’s register
. You can then use those APIs to:
- Add/remove event handlers
- Register custom widget types and React components used to render them
- Place items that will render your custom widgets
- Override React components to use when rendering insights
- Override React components to use when rendering KPIs
Furthermore, your event handlers and React components can use a subset of Model Selector APIs to obtain additional data from the current state of the dashboard.
Current limitations
- GoodData does not provide hosting for your built plugins. When you build your plugin, you will have to host it yourself in a publicly available location that supports HTTPS.
Before you start
A minimum setup is needed before your KPI Dashboards can start using plugins.
The setup is different for the GoodData platform and GoodData.CN.
Configuration on the GoodData platform
Set up hosting for the plugins, and request GoodData Support
to add it to the dashboardPluginHosts
setting.
This is a security measure. Only GoodData Support can add hosts to the dashboardPluginHosts
list.
The goal of this setting is to control from where the plugins can be loaded. This should
be a trusted and controlled location where only privileged developers can upload plugin artifacts.
You can request multiple hosts to be added to the list. All hosts must run on the HTTPS protocol.
IMPORTANT! Never put untrusted hosts into this list. Always put the hosts that are under your organization’s control and appropriate review and governance. Otherwise, you run risk of malicious code leaking your data.
Configuration on GoodData Cloud
Set up hosting for your plugins.
Update the Content Security Policy of your GoodData Cloud instance’s gateway to enable loading plugins from the hosting location.
Configuration on GoodData.CN
Set up hosting for your plugins.
Update the Content Security Policy of your GoodData.CN installation’s gateway to enable loading plugins from the hosting location.
Getting started
To start building the dashboard plugins, use the Plugin Development Toolkit.
The Toolkit comes with a CLI tool that helps you bootstrap a new plugin. To initialize a new plugin, run the following command:
npx @gooddata/plugin-toolkit dashboard-plugin init
You will be prompted to enter all the essentials, and then the tool will bootstrap a new plugin project for you. This project will contain a Walking Skeleton for your plugin including scripts to correctly build the plugin bundles.
The toolkit supports additional actions:
- Adding a plugin to a workspace
- Linking a dashboard with a plugin added to a workspace
- Unlinking a dashboard from a plugin
To learn more, follow the documentation in your new plugin’s README file. Happy coding!