Skip to content

Latest commit

 

History

History

whitelabelling_bar

README.md

1. Plugin - Whitelabelling Bar

This plugin adds a fixed bar to the bottom of the dashboard. The bar can display any text or an image or both depending on what is provided via plugin parameters.
The plugins is built to work with both Tiger/Panther and Bear backends.

The main use case for this plugin is to add custom branding that is always visible on the dashboards even when embedded using iFrame.

How to work with Whitelabelling Bar Plugin

  1. Clone this repository
  2. Navigate to whitelabelling_bar
  3. Provide backend, workspace and dashboard in .env
  4. Rename .env.secrets.template to .env.secrets and provide your preferred way of authentication
  5. Install dependencies (npm install or yarn install)
  6. See instructions below how to build, deploy, and use this plugin

Screenshot

Whitelabelling Bar

Plugin parameters

Plugin parameters should be an object with the following fields:

  • text: OPTIONAL - string to be displayed in the bar
  • logoUrl: OPTIONAL - URL of the image to be displayed in the bar
  • logoAltText: OPTIONAL - alt text for the image

Both text and logoUrl parameters are optional. If both are provided, the text will be displayed to the left of the logo. However, at least one of the parameters (text or logoUrl) must be provided otherwise the plugin will not load on the dashboard.

Sample parameters can be seen below:

{
    text: "Powered by\\xA0",
    // \\xA0 is a non-breaking space
    logoUrl: "https://www.gooddata.com/img/generic/logo-gd-b.svg",
    logoAltText: "GoodData",
}
  • NOTE: For convenience reasons, the Plugin Parameters object can be defined in the JSON5 format to avoid working with tricky quotes escaping when editing the parameters. See JSON5 documentation for more details.

2. General plugin documentation

GoodData.UI Dashboard Plugin project

This is a one-stop project to help you develop, test and build your own dashboard plugin. Before you start, we encourage you to learn more about plugins in our documentation.

In case you don't feel like reading the documentation at this point, go at least through the following quick introduction.

Quick Introduction into Dashboard Plugins

Dashboard Plugins (plugins) allow developers to create extensions that alter behavior and look and feel of the vanilla GoodData KPI Dashboards (dashboards).

Plugins are registered into the dashboard engine used to render a concrete dashboard. At the registration time the plugin code can use several customization APIs to:

  • deliver new custom widgets to render on the dashboard
  • alter how particular insights are rendered; this in effect allows you to inject custom data visualizations of analytics computed by GoodData
  • listen to events occurring on the dashboard

When developing your own plugin, you typically create custom React components and event handlers that interact with the rendered dashboard using available APIs and then register those components and handlers using the customization APIs.

The infrastructure within this project allows you to develop and verify your new plugin against a live, existing dashboard located either on GoodData platform or GoodData.CN.

Once you are happy with your new plugin you have to build it using scripts included in this project and then host the built artifacts.

After that, you can register the plugin into one or more workspaces on GoodData platform and/or GoodData.CN and then use the plugin on any number of dashboards

Note: GoodData currently does not provide hosting for your plugin artifacts.

Plugin development guide

Building a new plugin is easy. Before you start, ensure that your .env and .env.secrets files are set up correctly.

  1. (Optional) Export catalog: npm run refresh-md

    To make referencing various metadata objects easier in your plugin, you can use the Export catalog feature to get an easy-to-use list of the various MD objects in your workspace (insights, dashboards, attributes, etc.). For convenience, this was integrated to your plugin, just run npm run refresh-md. This will connect to the workspace specified in the .env file using the credentials from .env.secrets and populate the file src/md/full.ts with information about the metadata objects available in the specified workspace. See the Export catalog documentation page for more information.

  2. Start the development server: npm start

    To verify everything works correctly, navigate to https://127.0.0.1:3001. You should see your existing dashboard with a new empty section added at the end. The section will be titled 'Added from a plugin'.

    Note: you can use PORT env variable to specify different port number.

  3. Develop your plugin code in src/dp_whitelabelling_bar

    The src/dp_whitelabelling_bar/Plugin.tsx is the main plugin file where you have to register all your custom content. However, you can create as many new files as you want under the src/dp_whitelabelling_bar directory. Just make sure to never place your custom code outside of this directory.

    Note: we recommend to write your plugin in TypeScript and to use a modern IDE. This way you can conveniently explore the plugin customization APIs from the comfort of your development environment.

  4. Build the plugin: npm run build-plugin

    This will build plugin artifacts under esm/dashboardPlugin.

  5. Upload plugin artifacts to your hosting

    It is paramount that you upload all files from the esm/dashboardPlugin.

    IMPORTANT: your hosting must support https, allow CORS to your GoodData domain and your GoodData domain must include the hosting location in the list of allowed hosts from where GoodData will load plugins. You should create a support ticket to explicitly allow the hosting location before we will load any plugins from it. You may host multiple plugins in separate directories within the allowed hosting location.

    GOOD IDEA: treat plugin builds immutably. Never overwrite an already uploaded plugin artifacts. Organize your hosting location so there is always unique directory that contains all plugin artifacts. This is a corner-stone of controlled, phased rollout of the plugin.

    BAD IDEA: overwriting existing plugin artifacts will immediately impact all dashboards that use the plugin, possibly breaking them if you did not have chance to fully test the plugin.

  6. Add plugin to one or more workspaces: npm run add-plugin -- <url>

    Once your plugin is uploaded to public hosting location, you can add it into your workspace. You can achieve this using the same CLI tool that you have used to create this plugin project. For convenience, this project contains the tool among the devDependencies together with convenience script to add plugin to either workspace specified in your .env file (default) or another workspace that you specify on the command line.

    Run the npm run add-plugin -- "https://your.hosting/pluginDirOfYourChoice/dp_whitelabelling_bar.js" to create a new dashboard plugin object in the workspace specified in the .env file. The created dashboard object point to the URL of the built plugin.

    After successful creation of the plugin object, the tool will print plugin object identifier. You will need this identifier later to link dashboard(s) with the plugin.

    Note: the CLI tool has options that allow you to add plugin to different backends and/or different workspaces. Check out npm run gdc-plugins -- --help to learn more about the tool's commands and options.

  7. Use plugin on a dashboard: npm run link-plugin -- <plugin-object-id>

    Now that you have created a plugin object in your workspace, you can link it with one or more dashboards. The link-plugin script in package.json is a shortcut to link plugin with dashboard specified in your .env file.

    If your plugin supports parameterization ( see src/dp_whitelabelling_bar) and you want to specify parameters for the link between dashboard the plugin, you can run npm run link-plugin -- <plugin-object-id> --with-parameters and the tool will open an editor for you to enter the parameters.

    Note: the CLI tool has options that allow you to link plugin to different backends and/or different workspaces. Check out npm run gdc-plugins -- --help to learn more about the tool's commands and options.

    TIP: you can use the unlink command to remove the link between dashboard and the plugin.

  8. Update plugin parameters on a dashboard: npm run update-plugin-params -- <plugin-object-id>

    This command is useful if you want to change or add the parameters in the already linked plugin. The tool will open an editor for you to enter the new parameters.

  9. Remove plugin parameters on a dashboard: npm run remove-plugin-params -- <plugin-object-id>

    This command is useful if you want to remove the parameters in the already linked plugin.

Authentication & secrets

Your plugin does not have to concern itself with the authentication against GoodData backend. When the plugin runs in context of GoodData KPI Dashboards, it is the application that takes care of all the authentication and ensures that the plugin executes in an authenticated environment.

The authentication credentials that are required to start the development harness included in this project are used only during development because the harness needs to provide authenticated environment to the plugin as well.

In order to provide credentials to the development harness, you can use either the .env.secrets file or export the necessary environment variables before starting the harness.

The contents of .env.secrets will never make their way into plugin build artifacts, they are loaded only when starting the development harness. Check out the webpack.config.js if you would like to double-check this.

IMPORTANT: Never include credentials and secrets in your plugin source code or other assets that your plugin requires. All this data will be available in the publicly hosted plugin artifacts and can also be found through the browser developer console.

FAQ

What's up with the directories in src? Can I rename them?

Do not rename or otherwise refactor any of the directories that were created during this project initialization. The structure and naming are essential for the build and the runtime loading of your plugin to work properly.

This project is setup so that all your custom code must be self-contained in the src/dp_whitelabelling_bar directory.

The src/dp_whitelabelling_bar_engine and src/dp_whitelabelling_bar_entry directories contain essential plugin boilerplate. You should not modify these directories or their contents unless you are 100% sure what you are doing.

The [src/harness] directory contains code for plugin development harness; it is used only during plugin development and the code in this directory will not be part of the plugin build. You can start the harness using npm start. You should have no need to modify the code in the harness. We anticipate that at times you may need to tweak Analytical Backend setup that is contained in the src/harness/backend.ts - this is a safe change.

How can I set up compatibility of the plugin?

You can modify minEngineVersion and maxEngineVersion properties in src/dp_whitelabelling_bar\_entry/index. By default, we guarantee that plugin will be compatible only with the exact version of the dashboard engine used during its build ("bundled" option). But if you are sure, that plugin is compatible also with the other engine versions, you can set concrete range of the versions ( e.g. "minEngineVersion": "8.8.0", "maxEngineVersion": "8.9.0"). Note that combining multiple plugins created before version 8.8.0 may not work.

How do plugin dependencies work?

Your plugin can depend on arbitrary third party packages at your discretion with one exception: the packages specified as peerDependencies in this project's package.json. Packages that are listed as peerDependencies will be provided by the runtime environment.

Can I modify webpack config?

This is generally not recommended and if needed should be approached by expert users only. In general, adding new loaders and extending the resolve section are the safer types of changes. However, we strongly discourage making modifications to other parts of the webpack config: changes to how the dashboardPlugin is built can break your plugin and prevent it from loading correctly.

How about Internet Explorer?

GoodData's applications do not support Internet Explorer as of November 19th 2021. The plugin artifacts created during the plugin build are not compatible with Internet Explorer.

How about Safari?

GoodData's applications do support Safari, however currently it's not possible to run this boilerplate locally with GoodData.CN backend running on https protocol, due to the fact how Safari is handling authentication in backend redirects.

License

The Plugin can be utilized under the BSD-3 Clause License. For more details, please refer to the main LICENSE file available at ('../LICENSE')[LICENSE].