If you wish to construct your first GoodData Dashboard Plugin, this text will information you step-by-step by means of the entire course of.

What’s a GoodData Dashboard Plugin?

GoodData Dashboard Plugins supply builders the distinctive alternative to unleash their creativity and customise GoodData Dashboards in line with their particular person wants or enterprise targets. For instance, our Grouping Insights plugin permits builders to cluster related insights and easily transition between them utilizing a easy dropdown menu. This enhances not solely the visible group of knowledge but in addition the pace and comfort with which customers can navigate between completely different knowledge factors.

Our Dashboard Description plugin is one other shining instance of potential customizations. Not solely does it enable builders to include detailed descriptions into their dashboards, but it surely additionally helps dynamic attribute values and metrics. This introduces an unparalleled degree of context to your knowledge interpretation, permitting customers to simply perceive advanced datasets and make knowledgeable selections.

The potential for superior visualization can’t be overstated both. With visualizations plugins, builders can now showcase knowledge in intuitive ways in which had been beforehand unattainable. These instruments assist translate intricate knowledge into digestible visible narratives, driving house key insights and findings with much more affect.

From a technical perspective, the plugins are loaded as construct time dependency utilizing Webpack Module Federation they usually work together with the dashboard engine. On the time of registration, the plugin can entry a number of customization APIs to ship new customized widgets, modify the rendering of insights, and hearken to occasions occurring on the dashboard.

These plugins are designed to be registered to a workspace, after which they can be utilized on any variety of dashboards. This enables for scalable reusability throughout completely different dashboards, and for additional customization, the hyperlink between the dashboard and the plugin might be parameterized.

So, whether or not it is about refining knowledge navigation, enhancing comprehension, or telling compelling knowledge tales, GoodData Dashboard Plugins actually open up a world of prospects for builders. As a result of they use a considerate structure and fashionable applied sciences, GoodData Dashboard Plugins are designed with builders in thoughts, enabling them to reimagine and reinvent the way in which we work together with knowledge.

Getting Began with Dashboard Plugins

Step 1: Set up the Plugin Growth Toolkit

To shortly begin creating your plugin, we provide a Toolkit that makes the setup straightforward and easy. It comes with a Command Line Interface that guides you in naming the plugin, deciding on the GoodData backend sort, setting the Hostname, and opting between JavaScript and TypeScript. Whereas the Workspace and Dashboard ID are elective at this stage, they are often configured within the subsequent step.

To initialize a brand new plugin, run:

npx @gooddata/plugin-toolkit dashboard-plugin init

Step 2: Begin the Growth Server

As soon as the toolkit has created your new plugin, go to the generated folder. Guarantee your .env and .env.secrets and techniques information are arrange appropriately. The CLI ought to have already populated the .env file values through the set up course of. Nevertheless, within the .env.secrets and techniques file, you have to uncomment and fill the road containing TIGER_API_TOKEN if you’re utilizing GoodData.CN/GoodData Cloud, or GDC_USERNAME with GDC_PASSWORD if you’re utilizing GoodData Platform. The backend sort was chosen in step one, so your plugin is already configured to function with it.

With every thing set, you are prepared to start out the event server with npm begin. Confirm every thing is functioning correctly by opening https://127.0.0.1:3001. If profitable, you need to see your present dashboard with an added empty part titled ‘Added from a plugin’.

Step 3: Develop Your Plugin Code

Your principal plugin file shall be positioned at src/dp_<your_plugin_name>_plugin/Plugin.tsx. That is the place you will register all of your customized content material. Be at liberty to create as many new information and folders as you want, however notice that renaming generated folders and information may break the plugin’s performance.

Inside this file, you will observe the Register technique, which is the principle perform known as after the plugin mounts to the Dashboard’s DOM. The core code in your plugin must be known as right here. The onPluginLoaded and onPluginUnload strategies can be utilized to carry out particular initialization and cleanup duties, respectively.

An excellent place to begin is to pick out the Customise parameter from the Register technique and discover all of the potential strategies utilizing TypeScript’s autosuggestion and IDE Description. Incessantly used strategies embody customise.customWidgets().addCustomWidget() for including a brand new widget, customise.insightWidgets().withCustomProvider() for modifying an present widget (e.g., introducing new visualizations and utilizing knowledge from an present one), and customise.format().customizeFluidLayout() for including a brand new merchandise or part to the dashboard format.

When modifying an present widget, it is essential to find out how the plugin ought to determine which widget to alter. This may be achieved in a number of methods – by way of parameters, tags, suffixes/prefixes on widget titles, or visualization varieties. Your best option will rely in your particular use case. We advocate going by means of open-sourced dashboard plugins to grasp our strategy in several situations.

Lastly, keep in mind which you could entry your complete dashboard state utilizing the useDashboardSelector hook. Nevertheless, this can be a extra superior subject past the scope of this text.

Step 4: Construct the Plugin

Subsequent, construct the plugin by operating npm run build-plugin. This may create plugin artifacts below dist/dashboardPlugin.

Be aware that you should use dashboard plugins instantly with React Dashboard Element as Native Plugins if you find yourself constructing a customized FE software on high of GoodData.

Step 5: Add Plugin Artifacts to Your Internet hosting

Add all information from dist/dashboardPlugin to your internet hosting. Bear in mind, GoodData at present would not supply internet hosting in your plugin artifacts. Additionally, make sure that your internet hosting helps HTTPS and your GoodData area contains the internet hosting location within the listing of allowed hosts.

Step 6: Add Plugin to Workspaces

After your plugin is publicly hosted, combine it into your workspace utilizing the CLI so as to add the plugin to your default workspace (outlined in .env) or to a special workspace you specify.

Run the next command to create a brand new dashboard plugin object within the workspace, pointing to the URL of your plugin:

npm run add-plugin -- "https://your.internet hosting/pluginDirOfYourChoice/dp_test.js"

As soon as the plugin object is created, the final line of the terminal response ought to look one thing like this: “Created new plugin object with ID a8682044-3c57-4daf-9b00-05b082a3450”, you will want this identifier later to hyperlink the plugin with the dashboard.

Step 7: Use the Plugin on a Dashboard

Having created a plugin object in your workspace, you are now able to hyperlink it with a number of dashboards. The link-plugin script in package deal.json makes this straightforward by linking the plugin with the dashboard laid out in your .env file or you may override the .env with CLI choices.

npm run link-plugin -- <plugin-object-id>`

If you wish to reuse a plugin throughout completely different dashboards and customise its habits (e.g. appropriately show dashboard-specific textual content), specify extra parameters in every dashboard-plugin hyperlink. When specified, the parameters are despatched because the second argument to the onPluginLoad perform by the loader.

In case your plugin helps parameterization and also you wish to specify parameters for the dashboard-plugin hyperlink, use: npm run link-plugin -- <plugin-object-id> --with-parameters

An editor will open so that you can outline the enter parameters. Needless to say the CLI device can hyperlink the plugin to completely different backends or workspaces. Use npm run gdc-plugins -- --help to be taught extra.

For those who intend to make use of the plugin in manufacturing throughout a number of dashboards or workspaces, we advocate using the REST API through the provisioning automation course of. This may help you in distributing the plugin to all tenants.

Step 8 (Optionally available): Replace Plugin Parameters on a Dashboard

To replace or add parameters into an already linked plugin, use npm run update-plugin-params -- <plugin-object-id>.

Step 9 (Optionally available): Take away Plugin Parameters on a Dashboard

To take away the parameters from an already linked plugin, use npm run remove-plugin-params -- <plugin-object-id>.

Guaranteeing Safety

When creating your plugin, remember the fact that it doesn’t must deal with authentication towards the GoodData backend. Nevertheless, throughout improvement, the harness wants to offer an authenticated surroundings to the plugin. Subsequently, make sure that your credentials are safe and by no means embody them in your plugin supply code or different property.

Comfortable coding! 🚀

References