0
# Plugin Classes
1

2
Core plugin classes for registering word cloud charts with Apache Superset, supporting both modern and legacy API versions.
3

4
## Capabilities
5

6
### WordCloudChartPlugin
7

8
Modern chart plugin implementation for current Superset versions with full feature support.
9

10
```typescript { .api }
11
/**
12
 * Modern word cloud chart plugin extending ChartPlugin
13
 * Supports the latest Superset chart API with full control panel integration
14
 */
15
class WordCloudChartPlugin extends ChartPlugin<WordCloudFormData> {
16
  constructor();
17
}
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { WordCloudChartPlugin } from '@superset-ui/plugin-chart-word-cloud';
24

25
// Register the modern plugin
26
const plugin = new WordCloudChartPlugin();
27
plugin.configure({ key: 'word-cloud' }).register();
28
```
29

30
**Features:**
31
- Full control panel with chart customization options
32
- Modern form data handling with `WordCloudFormData` type
33
- Support for encodable visual encoding system
34
- Category metadata with tags and description
35
- Built-in chart examples and thumbnail
36

37
### LegacyWordCloudChartPlugin
38

39
Legacy chart plugin implementation for backward compatibility with older Superset versions.
40

41
```typescript { .api }
42
/**
43
 * Legacy word cloud chart plugin for backward compatibility
44
 * Uses legacy API with simplified form data structure
45
 */
46
class LegacyWordCloudChartPlugin extends ChartPlugin<LegacyWordCloudFormData> {
47
  constructor();
48
}
49
```
50

51
**Usage Example:**
52

53
```typescript
54
import { LegacyWordCloudChartPlugin } from '@superset-ui/plugin-chart-word-cloud';
55

56
// Register the legacy plugin
57
const legacyPlugin = new LegacyWordCloudChartPlugin();
58
legacyPlugin.configure({ key: 'legacy-word-cloud' }).register();
59
```
60

61
**Features:**
62
- Backward compatibility with older Superset versions
63
- Simplified form data with `LegacyWordCloudFormData` type
64
- Legacy API flag (`useLegacyApi: true`)
65
- Essential functionality without advanced control panel features
66

67
## Plugin Configuration
68

69
Both plugins are configured with the following components:
70

71
```typescript { .api }
72
interface PluginConfiguration {
73
  buildQuery: (formData: FormData) => QueryContext;
74
  loadChart: () => Promise<React.ComponentType>;
75
  metadata: ChartMetadata;
76
  transformProps: (chartProps: ChartProps) => WordCloudProps;
77
  controlPanel?: ControlPanelConfig;
78
}
79
```
80

81
### Build Query Function
82

83
Generates query configuration for data fetching from Superset backend with optional sorting by metric:
84

85
```typescript { .api }
86
/**
87
 * Builds query context for data fetching from Superset backend
88
 * Configures sorting by metric when sort_by_metric is enabled
89
 * @param formData - Chart form data configuration containing metric and sort preferences
90
 * @returns Query context with ordering and filtering options
91
 */
92
function buildQuery(formData: WordCloudFormData): QueryContext;
93
```
94

95
**Implementation Details:**
96
- Extracts `metric` and `sort_by_metric` from form data
97
- When `sort_by_metric` is true, adds descending order by the specified metric
98
- Uses `buildQueryContext` from `@superset-ui/core` for consistent query structure
99
- Returns array with single QueryObject containing base query plus optional ordering
100

101
### Chart Metadata
102

103
Metadata configuration for plugin registration:
104

105
```typescript { .api }
106
interface ChartMetadata {
107
  category: string;
108
  credits: string[];
109
  description: string;
110
  exampleGallery: Array<{ url: string }>;
111
  name: string;
112
  tags: string[];
113
  thumbnail: string;
114
  useLegacyApi?: boolean;
115
}
116
```
117

118
**Modern Plugin Metadata:**
119
- Category: "Ranking"
120
- Tags: "Aesthetic", "Categorical", "Comparison", "Description", "Density", "Single Metric"
121
- Credits: Links to d3-cloud library
122
- Example gallery with sample visualizations
123

124
**Legacy Plugin Metadata:**
125
- Simplified metadata structure
126
- `useLegacyApi: true` flag
127
- Essential information only
128

129
## Registration Process
130

131
```typescript
132
// Step 1: Import the desired plugin
133
import { WordCloudChartPlugin } from '@superset-ui/plugin-chart-word-cloud';
134

135
// Step 2: Create plugin instance
136
const plugin = new WordCloudChartPlugin();
137

138
// Step 3: Configure with unique key
139
plugin.configure({ key: 'word-cloud' });
140

141
// Step 4: Register with Superset
142
plugin.register();
143
```
144

145
The registration key ('word-cloud') is used throughout Superset to identify and reference this chart type in dashboards, explore view, and chart configuration.