From 1b35c77916b904e0039bbe9b8cb4957c82835d3f Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Wed, 12 Jan 2022 12:02:06 +0200 Subject: [PATCH 1/8] fix(generator): more cleanup to plugin framework --- .../generators/plugin-chart/index.js | 1 + .../plugin-chart/templates/README.erb | 70 +++++------ .../plugin-chart/templates/gitignore.erb | 111 ++++++++++++++++++ .../plugin-chart/templates/package.erb | 29 ++--- .../plugin-chart/templates/src/index.erb | 2 +- .../templates/src/plugin/index.erb | 2 +- .../plugin-chart/templates/test/index.erb | 6 +- .../test/plugin-chart.test.js | 1 + superset-frontend/webpack.config.js | 11 +- 9 files changed, 163 insertions(+), 70 deletions(-) create mode 100644 superset-frontend/packages/generator-superset/generators/plugin-chart/templates/gitignore.erb diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js b/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js index df76e0c99ee57..c8263a6aa135d 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js @@ -77,6 +77,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'], diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb index 2a117bbcf2f30..2180a1d5720f7 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb @@ -1,52 +1,40 @@ -## superset-plugin-chart-<%= packageName %> +# <%= packageName %> -This plugin provides <%= description %> for Superset. +This is the <%= description %>. ### Usage -Configure `key`, which can be any `string`, and register the plugin. This `key` will be used to lookup this chart throughout the app. +To build the plugin, run the following commands: -```js -import <%= packageLabel %>ChartPlugin from '@superset-ui/plugin-chart-<%= packageName %>'; +``` +npm i --force +npm run build +``` + +To run the plugin in development mode (=rebuilding whenever changes are made), start the dev server with the following command: -new <%= packageLabel %>ChartPlugin() - .configure({ key: '<%= packageName %>' }) - .register(); +``` +npm run dev +``` + +To add the package to Superset, go to the `superset-frontend` subdirectory in your Superset source folder (assuming both the `superset-plugin-chart-liquid` plugin and `superset` repos are in the same root directory) and run +``` +npm i -S ../../<%= packageName %> ``` -Then use it via `SuperChart`. See [storybook](https://apache-superset.github.io/superset-ui/?selectedKind=plugin-chart-<%= packageName %>) for more details. +After this edit the `superset-frontend/src/visualizations/presets/MainPreset.js` and make the following changes: ```js - -``` - -### File structure generated - -``` -├── package.json -├── README.md -├── tsconfig.json -├── src -│   ├── <%= packageLabel %>.tsx -│   ├── images -│   │   └── thumbnail.png -│   ├── index.ts -│   ├── plugin -│   │   ├── buildQuery.ts -│   │   ├── controlPanel.ts -│   │   ├── index.ts -│   │   └── transformProps.ts -│   └── types.ts -├── test -│   └── index.test.ts -└── types - └── external.d.ts +import { <%= packageLabel %> } from '<%= packageName %>'; +``` + +to import the plugin and later add the following to the array that's passed to the `plugins` property: +```js +new <%= packageLabel %>().configure({ key: '<%= packageName %>' }), +``` + +After that the plugin should show up when you run Superset, e.g. the development server: + +``` +npm run dev-server ``` diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/gitignore.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/gitignore.erb new file mode 100644 index 0000000000000..9aef7619cdc91 --- /dev/null +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/gitignore.erb @@ -0,0 +1,111 @@ +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# TypeScript v1 declaration files +typings/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test + +# parcel-bundler cache (https://parceljs.org/) +.cache + +# Next.js build output +.next + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and *not* Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# IDEs +.idea/ + +# build +esm +lib diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb index b06af71afbe2b..a6aa18f203718 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb @@ -1,7 +1,7 @@ { - "name": "superset-plugin-chart-<%= packageName %>", + "name": "<%= packageName %>", "version": "0.1.0", - "description": "Superset Chart - <%= description %>", + "description": "<%= description %>", "sideEffects": false, "main": "lib/index.js", "module": "esm/index.js", @@ -9,38 +9,35 @@ "esm", "lib" ], + "private": true, "scripts": { "build": "npm run build-cjs && npm run build-esm && npm run ts-types", "build-cjs": "babel src --extensions \".ts,.tsx,.js,.jsx\" --copy-files --out-dir lib", "build-clean": "npm run clean && npm run build", "build-esm": "BABEL_OUTPUT=esm babel src --extensions \".ts,.tsx,.js,.jsx\" --copy-files --out-dir esm", - "clean": "rm -rf {lib,esm,tsconfig.tsbuildinfo}", - "dev": "webpack --mode=development --color --watch", + "dev": "BABEL_OUTPUT=esm babel src --extensions \".ts,.tsx,.js,.jsx\" --watch --copy-files --out-dir esm", + "prebuild": "rimraf {lib,esm,tsconfig.tsbuildinfo}", + "postbuild": "npm run test", "ts-types": "tsc --build", "test": "jest" }, - "author": "Superset", + "author": "My Name", "license": "Apache-2.0", "publishConfig": { "access": "public" }, - "dependencies": { - }, + "dependencies": {}, "peerDependencies": { - "react": "^16.13.1", - "@superset-ui/core": "*", - "@superset-ui/chart-controls": "*" + "@superset-ui/chart-controls": "^0.18.25", + "@superset-ui/core": "^0.18.25", + "react": "^16.13.1" }, "devDependencies": { "@airbnb/config-babel": "^2.0.1", "@babel/cli": "^7.16.0", "@types/jest": "^26.0.4", - "babel-loader": "^8.2.2", - "clean-webpack-plugin": "^4.0.0", "jest": "^26.6.3", - "thread-loader": "^3.0.4", - "ts-loader": "^9.2.5", - "typescript": "^4.1.2", - "url-loader": "^4.1.1" + "rimraf": "^3.0.2", + "typescript": "^4.1.2" } } diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/index.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/index.erb index 21a23adaa91ec..879692fafd4f8 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/index.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/index.erb @@ -17,7 +17,7 @@ * under the License. */ // eslint-disable-next-line import/prefer-default-export -export { default as <%= packageLabel %>ChartPlugin } from './plugin'; +export { default as <%= packageLabel %> } from './plugin'; /** * Note: this file exports the default export from <%= packageLabel %>.tsx. * If you want to export multiple visualization modules, you will need to diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/plugin/index.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/plugin/index.erb index 6426df86fff84..7999042a0b1ef 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/plugin/index.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/src/plugin/index.erb @@ -22,7 +22,7 @@ import controlPanel from './controlPanel'; import transformProps from './transformProps'; import thumbnail from '../images/thumbnail.png'; -export default class <%= packageLabel %>ChartPlugin extends ChartPlugin { +export default class <%= packageLabel %> extends ChartPlugin { /** * The constructor is used to pass relevant metadata and callbacks that get * registered in respective registries that are used throughout the library diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/test/index.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/test/index.erb index 9eca957441a7c..9e427d9c7a3c5 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/test/index.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/test/index.erb @@ -16,7 +16,7 @@ * specific language governing permissions and limitations * under the License. */ -import { <%= packageLabel %>ChartPlugin } from '../src'; +import { <%= packageLabel %> } from '../src'; /** * The example tests in this file act as a starting point, and @@ -26,8 +26,8 @@ import { <%= packageLabel %>ChartPlugin } from '../src'; * treated correctly (e.g. formData from plugin controls * properly transform the data and/or any resulting props). */ -describe('@superset-ui/plugin-chart-<%= packageName %>', () => { +describe('<%= packageName %>', () => { it('exists', () => { - expect(<%= packageLabel %>ChartPlugin).toBeDefined(); + expect(<%= packageLabel %>).toBeDefined(); }); }); diff --git a/superset-frontend/packages/generator-superset/test/plugin-chart.test.js b/superset-frontend/packages/generator-superset/test/plugin-chart.test.js index d5f5f35f89703..15c280b169e77 100644 --- a/superset-frontend/packages/generator-superset/test/plugin-chart.test.js +++ b/superset-frontend/packages/generator-superset/test/plugin-chart.test.js @@ -40,6 +40,7 @@ test('generator-superset:plugin-chart:creates files', () => .withOptions({ skipInstall: true }) .then(function () { assert.file([ + '.gitignore', 'babel.config.js', 'jest.config.js', 'package.json', diff --git a/superset-frontend/webpack.config.js b/superset-frontend/webpack.config.js index c482706cd6c2f..1ea749fb836f9 100644 --- a/superset-frontend/webpack.config.js +++ b/superset-frontend/webpack.config.js @@ -285,7 +285,9 @@ const config = { // resolve modules from `/superset_frontend/node_modules` and `/superset_frontend` modules: ['node_modules', APP_DIR], alias: { - // TODO: remove alias once React has been upgraaded to v. 17 + // TODO: remove aliases once React has been upgraaded to v. 17 and + // AntD version conflict has been resolved + antd: path.resolve(path.join(APP_DIR, './node_modules/antd')), react: path.resolve(path.join(APP_DIR, './node_modules/react')), }, extensions: ['.ts', '.tsx', '.js', '.jsx', '.yml'], @@ -432,13 +434,6 @@ Object.entries(packageConfig.dependencies).forEach(([pkg, relativeDir]) => { const srcPath = path.join(APP_DIR, `./node_modules/${pkg}/src`); const dir = relativeDir.replace('file:', ''); - if (/^superset-plugin-/.test(pkg) && fs.existsSync(srcPath)) { - console.log( - `[Superset External Plugin] Use symlink source for ${pkg} @ ${dir}`, - ); - // TODO: remove alias once React has been upgraaded to v. 17 - config.resolve.alias[pkg] = path.resolve(APP_DIR, `${dir}/src`); - } if (/^@superset-ui/.test(pkg) && fs.existsSync(srcPath)) { console.log(`[Superset Plugin] Use symlink source for ${pkg} @ ${dir}`); config.resolve.alias[pkg] = path.resolve(APP_DIR, `${dir}/src`); From c7dbe3628f09e5e08f63df9f2373441f0b7c6758 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Fri, 14 Jan 2022 11:39:51 +0200 Subject: [PATCH 2/8] fix typo and package name --- .../generator-superset/generators/plugin-chart/index.js | 4 +--- .../generators/plugin-chart/templates/README.erb | 4 ++-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js b/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js index c8263a6aa135d..bbdd4936ec95d 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/index.js @@ -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', diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb index 2180a1d5720f7..7284e93296f45 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb @@ -1,6 +1,6 @@ # <%= packageName %> -This is the <%= description %>. +This is the <%= description %> Superset Chart Plugin. ### Usage @@ -17,7 +17,7 @@ To run the plugin in development mode (=rebuilding whenever changes are made), s npm run dev ``` -To add the package to Superset, go to the `superset-frontend` subdirectory in your Superset source folder (assuming both the `superset-plugin-chart-liquid` plugin and `superset` repos are in the same root directory) and run +To add the package to Superset, go to the `superset-frontend` subdirectory in your Superset source folder (assuming both the `<%= packageName %>` plugin and `superset` repos are in the same root directory) and run ``` npm i -S ../../<%= packageName %> ``` From bd5d12e92298f7eb487403560bd0742e76b8730b Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Fri, 14 Jan 2022 14:03:36 +0200 Subject: [PATCH 3/8] add docs --- .../Contributing/creating-viz-plugins.mdx | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/src/pages/docs/Contributing/creating-viz-plugins.mdx diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx new file mode 100644 index 0000000000000..a85bc99fddfea --- /dev/null +++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx @@ -0,0 +1,116 @@ +--- +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. 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 plugins by hand. + +### Prerequisites + +In order to create a new visualization plugin, you need the following: + +- Run MacOS or Linux (Windows is not officially supported, but may work) +- Node 16 +- npm 7 or 8 + +### Creating a simple Hello World 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/superset-generator +npm link +``` + +After this you can proceed to create your viz plugin. Create a new directory wherever +you have your repos (we'll assume under `~/src/`) with the prefix +`superset-plugin-chart` and run the Yeoman generator: + +```bash +cd ~/src +mkdir superset-plugin-chart-hello-world +cd superset-plugin-chart-hello-world +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 +identical .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 add the package to Superset, go to the `superset-frontend` subdirectory in your +Superset source folder (assuming both the `superset-plugin-chart-hello-world` plugin +and `superset` repos are in the same root directory) and run + +```bash +npm i -S ../../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 plugin and later add the following to the array that's passed to the +`plugins` property: + +```js +new SupersetPluginChartHelloWorld().configure({ key: 'superset-plugin-chart-hello-world' }), +``` + +After that the plugin should show up when you run Superset, e.g. the development server: + +```bash +npm run dev-server +``` From 907ba94f36028ae1e6dedf86bc9c167addfb3e42 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Fri, 14 Jan 2022 14:51:35 +0200 Subject: [PATCH 4/8] fix typo --- docs/src/pages/docs/Contributing/creating-viz-plugins.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx index a85bc99fddfea..ff001155f3c72 100644 --- a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx +++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx @@ -66,7 +66,7 @@ $ yo @superset-ui/superset ? Description: Hello World ? What type of chart would you like? Time-series chart create package.json -identical .gitignore + create .gitignore create babel.config.js create jest.config.js create README.md @@ -106,7 +106,7 @@ to import the plugin and later add the following to the array that's passed to t `plugins` property: ```js -new SupersetPluginChartHelloWorld().configure({ key: 'superset-plugin-chart-hello-world' }), +new SupersetPluginChartHelloWorld().configure({ key: 'ext-hello-world' }), ``` After that the plugin should show up when you run Superset, e.g. the development server: From 53dcca6b900e31c0d86a9d4d8f5f73804b6b1852 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt <33317356+villebro@users.noreply.github.com> Date: Fri, 14 Jan 2022 16:22:01 +0200 Subject: [PATCH 5/8] Update superset-frontend/webpack.config.js Co-authored-by: Kamil Gabryjelski --- superset-frontend/webpack.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/superset-frontend/webpack.config.js b/superset-frontend/webpack.config.js index 1ea749fb836f9..17547da5cd2f1 100644 --- a/superset-frontend/webpack.config.js +++ b/superset-frontend/webpack.config.js @@ -285,7 +285,7 @@ const config = { // resolve modules from `/superset_frontend/node_modules` and `/superset_frontend` modules: ['node_modules', APP_DIR], alias: { - // TODO: remove aliases once React has been upgraaded to v. 17 and + // TODO: remove aliases once React has been upgraded to v. 17 and // AntD version conflict has been resolved antd: path.resolve(path.join(APP_DIR, './node_modules/antd')), react: path.resolve(path.join(APP_DIR, './node_modules/react')), From 932f5271f9adee0a2cef8591c2477c7981bdf292 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Fri, 14 Jan 2022 17:30:49 +0200 Subject: [PATCH 6/8] fix generator reference --- docs/src/pages/docs/Contributing/creating-viz-plugins.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx index ff001155f3c72..021a345f2d78b 100644 --- a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx +++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx @@ -32,7 +32,7 @@ can be installed by doing the following: ```bash npm i -g yo -cd superset-frontend/packages/superset-generator +cd superset-frontend/packages/generator-superset npm link ``` From f93a9aaf3185ce68f43229adb2613cdaba7b2704 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Fri, 14 Jan 2022 18:24:34 +0200 Subject: [PATCH 7/8] add steps to tutorial and fix package version --- .../Contributing/creating-viz-plugins.mdx | 14 ++ .../installation/building-viz-plugins.mdx | 217 ------------------ .../plugin-chart/templates/README.erb | 2 +- .../plugin-chart/templates/package.erb | 4 +- 4 files changed, 17 insertions(+), 220 deletions(-) delete mode 100644 docs/src/pages/docs/installation/building-viz-plugins.mdx diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx index 021a345f2d78b..1f17fee69cae6 100644 --- a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx +++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx @@ -86,6 +86,20 @@ $ yo @superset-ui/superset create src/images/thumbnail.png ``` +To build the plugin, run the following commands: + +``` +npm i --force +npm run build +``` + +Alternatively, to run the 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 (assuming both the `superset-plugin-chart-hello-world` plugin and `superset` repos are in the same root directory) and run diff --git a/docs/src/pages/docs/installation/building-viz-plugins.mdx b/docs/src/pages/docs/installation/building-viz-plugins.mdx deleted file mode 100644 index c0a4efd93d36f..0000000000000 --- a/docs/src/pages/docs/installation/building-viz-plugins.mdx +++ /dev/null @@ -1,217 +0,0 @@ ---- -name: Building Custom Viz Plugins -menu: Installation and Configuration -route: /docs/installation/building-custom-viz-plugins -index: 12 -version: 1 ---- - -This is a tutorial to help you build a "Hello World" viz plugin. The intent is to provide a basic -scaffolding to build any sort of data visualization, using any viz libary you'd like (e.g. ECharts, -AntV, HighCharts, VX, and D3.). - -You can build the Hello World plugin by running a [Yeoman](https://yeoman.io/) generator, which -takes a few simple options, and provides this plugin scaffolding. - -## Getting Set Up - -### Install Yeoman and the Superset Package Generator - -This Hello World plugin we'll be building is generated automatically with -[Yeoman](https://yeoman.io/). Let's first get that installed by opening up a terminal and installing -both the `yo` module and the -[superset package generator](https://github.com/apache-superset/superset-ui/tree/master/packages/generator-superset) -(`v0.14.7`) to create the new plugin. - -``` -npm install -g yo @superset-ui/generator-superset -``` - -### Install Superset - -There are -[complete instructions](https://github.com/apache/superset#installation-and-configuration) -available on the [Superset Github repository](https://github.com/apache/superset). In a -nutshell, the easiest way is to: - -1. Have a Mac or linux-based machine -2. Install [Docker](https://docs.docker.com/get-docker/) -3. Clone [the repository](https://github.com/apache/superset) to your computer -4. Use your terminal to `cd` into the `superset` directory -5. Run `docker-compose up` -6. Open _another_ terminal, and `cd` into `superset/superset-frontend` -7. Run `npm install` to load up all the npm packages. -8. Run `npm run dev-server` to spin up the Webpack hot-reloading server -9. Wait for it to build, and then open your browser to `http://localhost:9000` and log in with - `admin`/`admin`. You're off to the races! (Note: we'll be restarting this later) - -### Install Superset-UI - -1. Clone [the `superset-ui` repository](https://github.com/apache-superset/superset-ui) to your - computer. It can sit in the same parent directory as your `superset` repo -2. Use your terminal to `cd` into `superset-ui` -3. Run `yarn install` and wait for all the packages to get installed - -## Build Your "Hello, World" - -### ~~Write~~ _generate_ some code! - -1. Using your terminal, `cd` into your local `superset-ui` repo folder and then into the `plugins` - subdirectory. -2. Make a new directory for your plugin, i.e. `mkdir plugin-chart-hello-world`. **Note:** we - _highly_ recommend following the `plugin-chart-your-plugin-name` pattern. -3. Now `cd plugin-chart-hello-world` -4. Finally, run `yo @superset-ui/superset` -5. Select `Create superset-ui chart plugin package` on the following screen: - -{' '} - -6. Give it a name (in our case, go with the default, based on the folder name): - - - -7. Give it a description (again, default is fine!) - - {' '} - -8. Choose which type of React component you want to make (Class, or Function component). - - {' '} - -9. Select whether you'd like your visualization to be timeseries-based or not - - {' '} - -10. Select whether or not you want to include badges at the top of your README file (really only - needed if you intend to contribute your plugin to the `superset-ui` repo). - - {' '} - -11. Admire all the files the generator has created for you. Note that EACH of these is chock full of - comments about what they're for, and how best to use them. - - {' '} - -### Add your Plugin to Superset (with NPM Link) - -Now, we want to see this thing actually RUN! To do that, we'll add your package to Superset and -embrace the magic power of `npm link` to see it in-situ, without needing to **build** the plugin, or -open any PRs on Github. - -1. Add your package to the `package.json` file in `superset/superset-frontend`. - - {' '} - -Note: Do _not_ run `npm install`... explanation below. - -2. Add your plugin to the `MainPreset.js` file (located in - `superset/superset-frontend/src/visualizations/presets/MainPreset.js`) in two places, - alongside the other plugins. - - {' '} - - {' '} - - -3. Open a terminal window to `superset/superset-frontend`. If you did the Install Superset - steps above, you may still have webpack running there, and you can just stop it with `ctrol-c`. - If not, just open a new window and or `cd` to that directory path. - -4) Use `npm link` to symlink plugin, using a relative path to `superset-ui` and your plugin folder, - e.g. `npm link ../../superset-ui/plugins/plugin-chart-hello-world`. - -5. Restart your webpack dev server with `npm run dev-server`. You'll know it worked if you see a - line stating - `[Superset Plugin] Use symlink source for @superset-ui/plugin-chart-hello-world @ ^0.0.0`. - -**NOTE:** If/when you do an `npm install` that erases the symlink generated by `npm link`, so you'll -have to redo those steps. - -**NOTE:** Dynamic import is a work in progress. We hope you won't even need to DO this soon. We'll -be blogging again when that day comes, we assure you. In short, we have a goal to make editing -`package.json` and `MainPreset.js` unnecessary, so all the code changes are made in ONE repo. - -### See it with your own eyes! - -You should now be able to go to the Explore view in your local Superset and add a new chart! You'll -see your new plugin when you go to select your viz type. - -{' '} - -Now you can load up some data, and you'll see it appear in the plugin! - -{' '} - -The plugin also outputs three things to your browser's console: - -- `formData`, a.k.a. everything sent into your viz from the controls -- `props`, as output from the `transformProps` file for your plugin's consumption -- The actual HTML element, which your plugin has hooks into for any necessary DOM maniupluation - -{' '} - -## Make it Your Own - -Now you're free to run wild with your new plugin! Here are a few places to start digging in: - -### Read the comments and docs - -Take a look through the full file tree of the plugin. The Readme gives details for the job of each -file. EACH of these files has been annotated with extensive comments of what the file is for, and -the basics of what you can do with it. - -### Take control! - -The plugin includes a couple of example controls, but you can certainly continue to add as many as -you need to. The comments/documentation within the controls file is a start, but we recommend -looking at existing `superset-ui` plugins for more examples of how you can implement controls to -enhance your queries, work with your data, and change your visualization's display. - -### Build the perfect query - -The `buildQuery` file where your plugin actually fetches data from the Superset backend. This file -builds he query "context" for your plugin. For a simple plugin, this file needn't do much. There are -a couple changes that need to be made for a timeseries plugin, thus the option in the Yeoman -generator. - -This file also allows you to add various post-processing operations, to have the Superset backend -process your data in various ways (pivoting, etc), but that's a whole other topic we'll cover -separately in the near future. - -### Style with Emotion - -Each of these methods lets you add custom CSS styles using Emotion 👩‍🎤(a CSS-in-JS approach) which -has access to Superset's burgeoning set of theme variables, and also automatically scopes the styles -to your plugin, so they don't "leak" to other areas of Superset. - -In the Hello World plugin, we've included a few example Theme variables (`colors`, `gridUnit`s, and -typographic weights/sizes). We'll be continuing to add more variables to this theme file as we -continue to push Superset (and the viz plugins) toward the standards of the Superset redesign (see -[SIP-34](https://github.com/apache/superset/issues/8976)) - -### Give it a thumbnail - -Because come on... that's the fun part, right? - -### Build it! - -In this tutorial, you built your plugin in the `superset-ui` repo. This means you can use the -built-in build scripts that the repo provides. With your terminal of choice, simply `cd` into the -root directory of `supeset-ui` and run `yarn build`. This will kick off a build of ALL the Superset -plugins and packages, including yours. - -### Test early, test often! - -The Hello World plugin includes some basic Jest tests to act as a starting point to add unit tests -to your plugin. These do a quick sanity check that the plugin actually loads correctly, and then run -through the basics of making sure that your controls are properly respected by modifying the -resulting data and/or props of the plugin. Running `yarn test` from the root directory of -`superset-ui` will run all the tests for plugins/packages, including your Hello World. - -### Deploying Custom Visualization to Production - -To deploy plugins to a production environment, you must have additional code -inside Superset that includes the npm packages of your plugins so they can be installed in the frontend. - - -One option is to build your Dockerfile so it contains your custom visualization packages. diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb index 7284e93296f45..55cb54bac429e 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/README.erb @@ -11,7 +11,7 @@ npm i --force npm run build ``` -To run the plugin in development mode (=rebuilding whenever changes are made), start the dev server with the following command: +Alternatively, to run the plugin in development mode (=rebuilding whenever changes are made), start the dev server with the following command: ``` npm run dev diff --git a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb index a6aa18f203718..2cf6c0027e638 100644 --- a/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb +++ b/superset-frontend/packages/generator-superset/generators/plugin-chart/templates/package.erb @@ -28,8 +28,8 @@ }, "dependencies": {}, "peerDependencies": { - "@superset-ui/chart-controls": "^0.18.25", - "@superset-ui/core": "^0.18.25", + "@superset-ui/chart-controls": "*", + "@superset-ui/core": "*", "react": "^16.13.1" }, "devDependencies": { From b262f59d618570f8e213330b96276579ee9c96e4 Mon Sep 17 00:00:00 2001 From: Ville Brofeldt Date: Mon, 17 Jan 2022 09:37:31 +0200 Subject: [PATCH 8/8] refine docs/readme --- .../Contributing/creating-viz-plugins.mdx | 43 +++++++++++-------- .../packages/generator-superset/README.md | 7 ++- 2 files changed, 28 insertions(+), 22 deletions(-) diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx index 1f17fee69cae6..352657487eca3 100644 --- a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx +++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx @@ -10,21 +10,24 @@ version: 1 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. Plugins are added to +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 plugins by hand. +of Superset, and add the custom built viz plugins by hand. ### Prerequisites -In order to create a new visualization plugin, you need the following: +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 16 +- Node.js 16 - npm 7 or 8 -### Creating a simple Hello World plugin +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 @@ -33,17 +36,21 @@ 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 wherever -you have your repos (we'll assume under `~/src/`) with the prefix -`superset-plugin-chart` and run the Yeoman generator: +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 -cd ~/src -mkdir superset-plugin-chart-hello-world -cd superset-plugin-chart-hello-world yo @superset-ui/superset ``` @@ -86,14 +93,14 @@ $ yo @superset-ui/superset create src/images/thumbnail.png ``` -To build the plugin, run the following commands: +To build the viz plugin, run the following commands: ``` npm i --force npm run build ``` -Alternatively, to run the plugin in development mode (=rebuilding whenever changes +Alternatively, to run the viz plugin in development mode (=rebuilding whenever changes are made), start the dev server with the following command: ``` @@ -101,11 +108,10 @@ npm run dev ``` To add the package to Superset, go to the `superset-frontend` subdirectory in your -Superset source folder (assuming both the `superset-plugin-chart-hello-world` plugin -and `superset` repos are in the same root directory) and run +Superset source folder run ```bash -npm i -S ../../superset-plugin-chart-hello-world +npm i -S /tmp/superset-plugin-chart-hello-world ``` If you publish your package to npm, you can naturally install directly from there, too. @@ -116,14 +122,15 @@ and make the following changes: import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world'; ``` -to import the plugin and later add the following to the array that's passed to the +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 plugin should show up when you run Superset, e.g. the development server: +After that the viz plugin should show up when you run Superset, e.g. the development +server: ```bash npm run dev-server diff --git a/superset-frontend/packages/generator-superset/README.md b/superset-frontend/packages/generator-superset/README.md index 0f6ad54ef504c..3c90c818740d0 100644 --- a/superset-frontend/packages/generator-superset/README.md +++ b/superset-frontend/packages/generator-superset/README.md @@ -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 ```