Merge pull request apache#58 from tgunther-zerofox/ZFE-79465-add-samp…

…le-plugins

Add sample plugins and instructions to add more

docs/README.md

@@ -57,11 +57,10 @@ in case that you need to update this repo:
     2. Updating by a handmade fix
 2. Manually regenerate API changes:
     - At superset/initialization/__init__.py
-   ```
-   from superset.zf_integration.api import ZFIntegrationRestApi
-   ...
-   ...
-      appbuilder.add_api(ZFIntegrationRestApi)
+   ```python
+    from superset.zf_integration.api import ZFIntegrationRestApi
+
+    appbuilder.add_api(ZFIntegrationRestApi)
    ```
 3. Confirm that the folders address on the docker compose are still valid, to transfer our custom code into the superset project.
 

docs/add-new-plugin.md

@@ -0,0 +1,93 @@
+# Add new plugin
+
+To facilitate the process to add a new plugin, there are two samples that can be copied and edited.
+
+## SampleBlankPlugin
+
+This one is a React Component that can be overwriten with any logic for both processing and visualizing data. The base code was obtained by following the official tutorial here: https://superset.apache.org/docs/contributing/creating-viz-plugins/
+
+To create a new one:
+
+1. Copy `superset-frontend/plugins/plugin-sample-blank-chart` to a folder with a name for the new plugin
+2. Replace `PluginSampleBlankChart` with the name of the new chart
+3. There are two kinds of charts: Regular or Time Series. If your new chart is a Time Series one, you need to:
+  a. Uncomment block on superset-frontend/plugins/<name>/src/plugin/transformProps.ts:63-68
+  b. Uncomment line on superset-frontend/plugins/<name>/src/plugin/buildQuery.ts:42
+4. Write the code you need
+
+Finally you just need to import and load the package into superset-frontend/src/visualizations/presets/MainPreset.js
+
+```js
+import { PluginName } from 'plugins/<plugin-name>/src';
+// ...
+new PluginName().configure({ key: plugin-name }),
+```
+
+Now to run the code you need to recompile the frontend with `ASSET_BASE_URL=http://localhost:8000/spa_bff/superset npm run build-dev`. The plugin should be available to be used on a new Chart
+
+## Echart plugin
+
+Superset has many plugins integrated from echarts (https://echarts.apache.org/examples/en/index.html), but not all of them. If a chart is on the examples, is possible to integrate it by reusing some of the logic on an existing plugin.
+
+This guide will show an example on how to integrate a new chart from echart. It will integrate the Calendar Heatmap Chart that is not integrated (currently Superset has a legacy Calendar Heatmap Chart that is not from echarts).
+
+1. Copy `superset-frontend/plugins/plugin-chart-echarts/src/SampleChart`  to a folder with a name for the new plugin
+2. Replace SampleChart with the name of the chart
+3. The most important file to overwrite is the `TransformProps.ts`, where you need to specify the options of the chart that are on the Echart website
+4. Write other files as needed
+5. Export it on `superset-frontend/plugins/plugin-chart-echarts/src/index.ts`
+
+Finally you just need to import and load the package into `superset-frontend/src/visualizations/presets/MainPreset.js`
+
+```js
+import { PluginName } from 'plugins/<plugin-name>/src';
+// ...
+new PluginName().configure({ key: plugin-name }),
+```
+
+Now to run the code you need to recompile the frontend with `ASSET_BASE_URL=http://localhost:8000/spa_bff/superset npm run build-dev`. The plugin should be available to be used on a new Chart
+
+# References
+
+- https://echarts.apache.org/examples/en/index.html
+- https://superset.apache.org/docs/contributing/creating-viz-plugins/
+
+# File references
+
+All plugins charts have the same structure:
+
+## types.ts
+
+Defines the basic types of the plugin. In the code generated sample it includes StylesProps and CustomizeProps. The first one refers to visual (CSS) and the second to props to customize data to be visualized.
+
+It also defines QueryFormData, which is a combination of Superset QueryFormData, StylesProps and CustomizeProps. The QueryFormData is the data that is passed into the chart to be visualized.
+
+## .TSX file
+
+The props are used on the React Component. In the base example, this file contains the CSS styles and HTML structure that is going to be rendered. It also render a simple <pre> block to render a simple JSON with the data passed into the chart:
+
+## buildQuery.ts
+
+This file is used to preprocess the arguments that are going to be passed into the request that is made to the backend to fetch the data.
+
+In here you can use any of the values defined on the ControlPanel.ts
+
+## controlPanel.ts
+
+In here you can customize and add selectors to the chart
+
+There are two sections, where usually the first one is the filters to query the data and the second is to customize the visual appearance of the chart.
+
+In the example, the section Customize matches all the Props that are passed into the ReactComponent.
+
+## index.ts
+
+This file defines some sample metadata of the plugin, like the tile, description, tags and so on. It is good to look into an existing plugin to review all the available options.
+
+## transformProps.ts
+
+This code is executed when the data is returned from the backend. Here you can customize and process the data to match the visualization specifications.
+
+## ./images/thumbnail
+
+The thumbnail to be shown when the Plugin Chart is selected when creating a new Chart.

mkdocs.yml

@@ -4,5 +4,6 @@ nav:
     - Home: README.md
     - Release+Deploy: RELEASE+DEPLOY.md
     - Testing: TESTING.md
+    - New Plugin: add-new-plugin.md
 plugins:
     - techdocs-core

superset-frontend/plugins/plugin-chart-echarts/src/SampleChart/SampleChart.tsx

@@ -0,0 +1,84 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import React, { useCallback } from 'react';
+import { SampleChartTransformedProps } from './types';
+import Echart from '../components/Echart';
+import { allEventHandlers } from '../utils/eventHandlers';
+
+export default function EchartsSampleChart(props: SampleChartTransformedProps) {
+  const {
+    height,
+    width,
+    echartOptions,
+    setDataMask,
+    labelMap,
+    groupby,
+    selectedValues,
+    emitCrossFilters,
+    refs,
+  } = props;
+  const handleChange = useCallback(
+    (values: string[]) => {
+      if (!emitCrossFilters) {
+        return;
+      }
+
+      const groupbyValues = values.map(value => labelMap[value]);
+
+      setDataMask({
+        extraFormData: {
+          filters:
+            values.length === 0
+              ? []
+              : groupby.map((col, idx) => {
+                  const val = groupbyValues.map(v => v[idx]);
+                  if (val === null || val === undefined)
+                    return {
+                      col,
+                      op: 'IS NULL',
+                    };
+                  return {
+                    col,
+                    op: 'IN',
+                    val: val as (string | number | boolean)[],
+                  };
+                }),
+        },
+        filterState: {
+          value: groupbyValues.length ? groupbyValues : null,
+          selectedValues: values.length ? values : null,
+        },
+      });
+    },
+    [groupby, labelMap, setDataMask, selectedValues],
+  );
+
+  const eventHandlers = allEventHandlers(props, handleChange);
+
+  return (
+    <Echart
+      refs={refs}
+      height={height}
+      width={width}
+      echartOptions={echartOptions}
+      eventHandlers={eventHandlers}
+      selectedValues={selectedValues}
+    />
+  );
+}

superset-frontend/plugins/plugin-chart-echarts/src/SampleChart/buildQuery.ts

@@ -0,0 +1,45 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { buildQueryContext, QueryFormData } from '@superset-ui/core';
+
+/**
+ * The buildQuery function is used to create an instance of QueryContext that's
+ * sent to the chart data endpoint. In addition to containing information of which
+ * datasource to use, it specifies the type (e.g. full payload, samples, query) and
+ * format (e.g. CSV or JSON) of the result and whether or not to force refresh the data from
+ * the datasource as opposed to using a cached copy of the data, if available.
+ *
+ * More importantly though, QueryContext contains a property `queries`, which is an array of
+ * QueryObjects specifying individual data requests to be made. A QueryObject specifies which
+ * columns, metrics and filters, among others, to use during the query. Usually it will be enough
+ * to specify just one query based on the baseQueryObject, but for some more advanced use cases
+ * it is possible to define post processing operations in the QueryObject, or multiple queries
+ * if a viz needs multiple different result sets.
+ */
+export default function buildQuery(formData: QueryFormData) {
+  const { cols: groupby } = formData;
+  return buildQueryContext(formData, baseQueryObject => [
+    {
+      ...baseQueryObject,
+      groupby,
+      // uncomment if the chart is a timeseries one
+      // is_timeseries: true,
+    },
+  ]);
+}