Skip to content

Commit

Permalink
fix(generator): more cleanup to plugin framework (#18027)
Browse files Browse the repository at this point in the history
* fix(generator): more cleanup to plugin framework

* fix typo and package name

* add docs

* fix typo

* Update superset-frontend/webpack.config.js

Co-authored-by: Kamil Gabryjelski <kamil.gabryjelski@gmail.com>

* fix generator reference

* add steps to tutorial and fix package version

* refine docs/readme

Co-authored-by: Kamil Gabryjelski <kamil.gabryjelski@gmail.com>
  • Loading branch information
villebro and kgabryje authored Jan 17, 2022
1 parent de8a1fa commit 8dea7f5
Show file tree
Hide file tree
Showing 12 changed files with 303 additions and 293 deletions.
137 changes: 137 additions & 0 deletions docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
---
name: Creating Visualization Plugins
menu: Contributing
route: /docs/contributing/creating-viz
index: 9
version: 1
---

## Creating Visualization Plugins

Visualizations in Superset are implemented in JavaScript or TypeScript. Superset
comes preinstalled with several visualizations types (hereafter "viz plugins") that
can be found under the `superset-frontend/plugins` directory. Viz plugins are added to
the application in the `superset-frontend/src/visualizations/presets/MainPreset.js`.
The Superset project is always happy to review proposals for new high quality viz
plugins. However, for highly custom viz types it is recommended to maintain a fork
of Superset, and add the custom built viz plugins by hand.

### Prerequisites

In order to create a new viz plugin, you need the following:

- Run MacOS or Linux (Windows is not officially supported, but may work)
- Node.js 16
- npm 7 or 8

A general familiarity with [React](https://reactjs.org/) and the npm/Node system is
also recommended.

### Creating a simple Hello World viz plugin

To get started, you need the Superset Yeoman Generator. It is recommended to use the
version of the template that ships with the version of Superset you are using. This
can be installed by doing the following:

```bash
npm i -g yo
cd superset-frontend/packages/generator-superset
npm i
npm link
```

After this you can proceed to create your viz plugin. Create a new directory for your
viz plugin with the prefix `superset-plugin-chart` and run the Yeoman generator:

```bash
mkdir /tmp/superset-plugin-chart-hello-world
cd /tmp/superset-plugin-chart-hello-world
```

Initialize the viz plugin:

```bash
yo @superset-ui/superset
```

After that the generator will ask a few questions (the defaults should be fine):

```
$ yo @superset-ui/superset
_-----_ ╭──────────────────────────╮
| | │ Welcome to the │
|--(o)--| │ generator-superset │
`---------´ │ generator! │
( _´U`_ ) ╰──────────────────────────╯
/___A___\ /
| ~ |
__'.___.'__
´ ` |° ´ Y `
? Package name: superset-plugin-chart-hello-world
? Description: Hello World
? What type of chart would you like? Time-series chart
create package.json
create .gitignore
create babel.config.js
create jest.config.js
create README.md
create tsconfig.json
create src/index.ts
create src/plugin/buildQuery.ts
create src/plugin/controlPanel.ts
create src/plugin/index.ts
create src/plugin/transformProps.ts
create src/types.ts
create src/SupersetPluginChartHelloWorld.tsx
create test/index.test.ts
create test/__mocks__/mockExportString.js
create test/plugin/buildQuery.test.ts
create test/plugin/transformProps.test.ts
create types/external.d.ts
create src/images/thumbnail.png
```

To build the viz plugin, run the following commands:

```
npm i --force
npm run build
```

Alternatively, to run the viz plugin in development mode (=rebuilding whenever changes
are made), start the dev server with the following command:

```
npm run dev
```

To add the package to Superset, go to the `superset-frontend` subdirectory in your
Superset source folder run

```bash
npm i -S /tmp/superset-plugin-chart-hello-world
```

If you publish your package to npm, you can naturally install directly from there, too.
After this edit the `superset-frontend/src/visualizations/presets/MainPreset.js`
and make the following changes:

```js
import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world';
```

to import the viz plugin and later add the following to the array that's passed to the
`plugins` property:

```js
new SupersetPluginChartHelloWorld().configure({ key: 'ext-hello-world' }),
```

After that the viz plugin should show up when you run Superset, e.g. the development
server:

```bash
npm run dev-server
```
217 changes: 0 additions & 217 deletions docs/src/pages/docs/installation/building-viz-plugins.mdx

This file was deleted.

7 changes: 3 additions & 4 deletions superset-frontend/packages/generator-superset/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,11 @@ npm install -g @superset-ui/generator-superset

## Usage

Generate a new package or visualization plugin in `@superset-ui`
Generate a new package or visualization plugin:

```bash
cd superset-ui/packages
mkdir superset-ui-new-package
cd superset-ui-new-package
mkdir /tmp/superset-plugin-chart-hello-world
cd /tmp/superset-plugin-chart-hello-world
yo @superset-ui/superset
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,7 @@ module.exports = class extends Generator {
name: 'packageName',
message: 'Package name:',
// Default to current folder name
default: _.kebabCase(
this.appname.replace('superset plugin chart', '').trim(),
),
default: _.kebabCase(this.appname),
},
{
type: 'input',
Expand Down Expand Up @@ -77,6 +75,7 @@ module.exports = class extends Generator {
};

[
['gitignore.erb', '.gitignore'],
['babel.config.erb', 'babel.config.js'],
['jest.config.erb', 'jest.config.js'],
['package.erb', 'package.json'],
Expand Down
Loading

0 comments on commit 8dea7f5

Please sign in to comment.