0
# Control Panel Configuration
1

2
Configuration system for the word cloud chart control panel that defines user interface controls for chart customization within Superset's explore view.
3

4
## Capabilities
5

6
### Control Panel Config
7

8
Main configuration object that defines all user interface controls and sections for the word cloud chart.
9

10
```typescript { .api }
11
/**
12
 * Control panel configuration for word cloud chart
13
 * Defines sections, controls, and validation rules for the UI
14
 */
15
interface ControlPanelConfig {
16
  controlPanelSections: ControlPanelSection[];
17
  controlOverrides?: Record<string, Partial<ControlConfig>>;
18
}
19

20
interface ControlPanelSection {
21
  label: string;
22
  expanded: boolean;
23
  controlSetRows: (string | ControlSetRow)[][];
24
}
25

26
interface ControlSetRow {
27
  name: string;
28
  config: ControlConfig;
29
}
30
```
31

32
## Control Panel Sections
33

34
### Legacy Regular Time Section
35

36
Inherited time-based controls for temporal data filtering:
37

38
```typescript { .api }
39
// Uses sections.legacyRegularTime from @superset-ui/chart-controls
40
const timeSection = sections.legacyRegularTime;
41
```
42

43
### Query Section
44

45
Core data selection and querying controls:
46

47
```typescript { .api }
48
interface QuerySection {
49
  label: 'Query';
50
  expanded: true;
51
  controlSetRows: [
52
    ['series'],        // Text field selection (required, non-empty)
53
    ['metric'],        // Metric selection for sizing
54
    ['adhoc_filters'], // Dynamic filtering
55
    ['row_limit'],     // Result count limit (default: 100)
56
    ['sort_by_metric'] // Checkbox for metric-based sorting
57
  ];
58
}
59
```
60

61
**Query Controls:**
62

63
- **series**: Required text field for word content (validated with `validateNonEmpty`)
64
- **metric**: Numeric field for determining word sizes
65
- **adhoc_filters**: Dynamic filter configuration
66
- **row_limit**: Maximum number of results (default: 100)
67
- **sort_by_metric**: Boolean checkbox to sort results by metric value in descending order
68

69
### Options Section
70

71
Visual appearance and formatting controls:
72

73
```typescript { .api }
74
interface OptionsSection {
75
  label: 'Options';
76
  expanded: true;
77
  controlSetRows: [
78
    ['size_from', 'size_to'], // Font size range controls
79
    ['rotation'],             // Word rotation pattern
80
    ['color_scheme']          // Color scheme selection
81
  ];
82
}
83
```
84

85
**Font Size Controls:**
86

87
```typescript { .api }
88
interface FontSizeControls {
89
  size_from: {
90
    type: 'TextControl';
91
    isInt: true;
92
    label: 'Minimum Font Size';
93
    default: 10;
94
    description: 'Font size for the smallest value in the list';
95
  };
96
  size_to: {
97
    type: 'TextControl';
98
    isInt: true;
99
    label: 'Maximum Font Size';
100
    default: 70;
101
    description: 'Font size for the biggest value in the list';
102
  };
103
}
104
```
105

106
**Rotation Control:**
107

108
```typescript { .api }
109
interface RotationControl {
110
  type: 'SelectControl';
111
  label: 'Word Rotation';
112
  choices: [
113
    ['random', 'random'],
114
    ['flat', 'flat'],
115
    ['square', 'square']
116
  ];
117
  default: 'square';
118
  clearable: false;
119
  description: 'Rotation to apply to words in the cloud';
120
}
121
```
122

123
**Color Scheme Control:**
124

125
```typescript { .api }
126
// Uses standard color_scheme control from @superset-ui/chart-controls
127
const colorSchemeControl = 'color_scheme';
128
```
129

130
## Control Overrides
131

132
Custom validation and default value overrides for specific controls:
133

134
```typescript { .api }
135
interface ControlOverrides {
136
  series: {
137
    validators: [typeof validateNonEmpty];
138
    clearable: false;
139
  };
140
  row_limit: {
141
    default: 100;
142
  };
143
}
144
```
145

146
**Override Details:**
147

148
- **series override**: Ensures the text field is required and cannot be cleared
149
- **row_limit override**: Sets default result limit to 100 records
150

151
## Control Types
152

153
### TextControl
154

155
Integer input controls for numeric values:
156

157
```typescript { .api }
158
interface TextControl {
159
  type: 'TextControl';
160
  isInt: true;
161
  label: string;
162
  renderTrigger: boolean;
163
  default: number;
164
  description: string;
165
}
166
```
167

168
### SelectControl
169

170
Dropdown selection controls with predefined choices:
171

172
```typescript { .api }
173
interface SelectControl {
174
  type: 'SelectControl';
175
  label: string;
176
  choices: [string, string][];
177
  renderTrigger: boolean;
178
  default: string;
179
  clearable: boolean;
180
  description: string;
181
}
182
```
183

184
### CheckboxControl
185

186
Boolean toggle controls:
187

188
```typescript { .api }
189
interface CheckboxControl {
190
  type: 'CheckboxControl';
191
  label: string;
192
  description: string;
193
}
194
```
195

196
## Validation System
197

198
### Built-in Validators
199

200
```typescript { .api }
201
/**
202
 * Validates that a field has a non-empty value
203
 * Prevents form submission with empty required fields
204
 */
205
function validateNonEmpty(value: any): string | false;
206
```
207

208
**Usage Example:**
209

210
```typescript
211
controlOverrides: {
212
  series: {
213
    validators: [validateNonEmpty],
214
    clearable: false,
215
  }
216
}
217
```
218

219
## Integration with Superset
220

221
### Dependencies
222

223
```typescript { .api }
224
import { t, validateNonEmpty } from '@superset-ui/core';
225
import { ControlPanelConfig, sections } from '@superset-ui/chart-controls';
226
```
227

228
### Localization
229

230
All user-facing strings use the `t()` function for internationalization:
231

232
```typescript
233
label: t('Query'),
234
description: t('Font size for the smallest value in the list'),
235
```
236

237
### Standard Controls
238

239
Leverages Superset's standard control library:
240

241
- **sections.legacyRegularTime**: Time-based filtering controls
242
- **'series'**: Standard field selection control
243
- **'metric'**: Standard metric selection control
244
- **'adhoc_filters'**: Dynamic filter builder
245
- **'row_limit'**: Result count limiter
246
- **'color_scheme'**: Color scheme selector
247

248
## Configuration Export
249

250
```typescript
251
const config: ControlPanelConfig = {
252
  controlPanelSections: [
253
    sections.legacyRegularTime,
254
    querySection,
255
    optionsSection
256
  ],
257
  controlOverrides: {
258
    series: { validators: [validateNonEmpty], clearable: false },
259
    row_limit: { default: 100 }
260
  }
261
};
262

263
export default config;
264
```
265

266
This configuration creates a comprehensive control panel that allows users to:
267

268
1. Select time ranges and apply filters
269
2. Choose text and metric fields for the word cloud
270
3. Configure visual appearance (font sizes, rotation, colors)
271
4. Control data processing (sorting, result limits)
272
5. Validate required inputs before chart generation