0
# Legacy Plugin Chart World Map
1
2
A legacy world map chart plugin for Apache Superset that enables interactive geographical data visualization through choropleth mapping and bubble overlays. Built with D3.js and datamaps, it provides both React and functional APIs for creating world maps in Superset dashboards.
3
4
## Package Information
5
6
- **Package Name**: @superset-ui/legacy-plugin-chart-world-map
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @superset-ui/legacy-plugin-chart-world-map`
10
11
## Core Imports
12
13
```typescript
14
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
15
```
16
17
For ES modules:
18
```javascript
19
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
20
```
21
22
For CommonJS:
23
```javascript
24
const WorldMapChartPlugin = require('@superset-ui/legacy-plugin-chart-world-map');
25
```
26
27
## Basic Usage
28
29
```javascript
30
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
31
32
// Create and register the plugin with Superset
33
const worldMapPlugin = new WorldMapChartPlugin();
34
// Note: Registration with Superset is typically handled by the framework
35
36
// Use with SuperChart
37
<SuperChart
38
chartType="world-map"
39
width={600}
40
height={600}
41
formData={{
42
entity: 'country',
43
countryFieldtype: 'cca2',
44
colorBy: 'metric',
45
showBubbles: false,
46
maxBubbleSize: 25,
47
// ... other configuration options
48
}}
49
queriesData={[{
50
data: [
51
{
52
country: 'US',
53
name: 'United States',
54
latitude: 39.8283,
55
longitude: -98.5795,
56
m1: 1000, // Primary metric (for choropleth)
57
m2: 500 // Secondary metric (for bubble size)
58
},
59
// ... more country data
60
],
61
}]}
62
/>
63
```
64
65
## Architecture
66
67
The plugin is built around several key components:
68
69
- **WorldMapChartPlugin**: Main plugin class that extends ChartPlugin and integrates with Superset's chart system
70
- **WorldMap Function**: Core D3.js-based visualization implementation using datamaps
71
- **ReactWorldMap Component**: Styled React component wrapper that integrates the WorldMap function with Superset's theming
72
- **transformProps Function**: Data transformation layer that converts Superset chart props to WorldMap component props
73
- **Control Panel Configuration**: TypeScript configuration object defining the chart customization interface
74
- **ColorBy Enum**: Utility enum defining color mapping strategies
75
76
## Capabilities
77
78
### Plugin Registration
79
80
Main plugin class for registering the world map chart with Superset.
81
82
```typescript { .api }
83
class WorldMapChartPlugin extends ChartPlugin {
84
constructor();
85
}
86
```
87
88
The plugin includes comprehensive metadata:
89
90
```typescript { .api }
91
interface ChartMetadata {
92
category: string; // 'Map'
93
credits: string[]; // ['http://datamaps.github.io/']
94
description: string; // Chart description
95
exampleGallery: { url: string }[];
96
name: string; // 'World Map'
97
tags: string[]; // Chart classification tags
98
thumbnail: string; // Thumbnail image path
99
useLegacyApi: boolean; // true
100
behaviors: Behavior[]; // [Behavior.DRILL_TO_DETAIL]
101
}
102
```
103
104
### World Map Visualization
105
106
Core D3.js-based world map visualization function.
107
108
```typescript { .api }
109
function WorldMap(element: HTMLElement, props: WorldMapProps): void;
110
111
interface WorldMapProps {
112
data: CountryData[];
113
width: number;
114
height: number;
115
maxBubbleSize: number;
116
showBubbles: boolean;
117
linearColorScheme: string;
118
color: string;
119
colorBy: ColorBy;
120
colorScheme: string;
121
countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
122
entity: string;
123
sliceId: string | number;
124
theme: SupersetTheme;
125
onContextMenu: (x: number, y: number, filters: Filter[]) => void;
126
inContextMenu: boolean;
127
}
128
129
interface CountryData {
130
country: string; // Country code (format depends on countryFieldtype)
131
latitude: number; // Country latitude for bubble placement
132
longitude: number; // Country longitude for bubble placement
133
name: string; // Display name for tooltips
134
m1: number; // Primary metric for choropleth coloring
135
m2: number; // Secondary metric for bubble sizing
136
}
137
138
interface Filter {
139
col: string;
140
op: string;
141
val: any;
142
formattedVal: any;
143
}
144
```
145
146
### React Component
147
148
Styled React wrapper component that integrates WorldMap with Superset's theming system.
149
150
```typescript { .api }
151
interface WorldMapComponent {
152
(props: { className: string } & WorldMapProps): JSX.Element;
153
}
154
155
// The default export is a styled component
156
const StyledWorldMapComponent: React.ComponentType<{
157
className: string;
158
} & WorldMapProps>;
159
```
160
161
162
### Props Transformation
163
164
Transform Superset chart props to WorldMap component props.
165
166
```typescript { .api }
167
function transformProps(chartProps: SupersetChartProps): WorldMapProps;
168
169
interface SupersetChartProps {
170
width: number;
171
height: number;
172
formData: FormData;
173
queriesData: QueryData[];
174
hooks: {
175
onContextMenu: (x: number, y: number, filters: Filter[]) => void;
176
};
177
inContextMenu: boolean;
178
}
179
180
interface FormData {
181
countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
182
entity: string;
183
maxBubbleSize: string;
184
showBubbles: boolean;
185
linearColorScheme: string;
186
colorPicker: { r: number; g: number; b: number };
187
colorBy: ColorBy;
188
colorScheme: string;
189
sliceId: string | number;
190
}
191
192
interface QueryData {
193
data: CountryData[];
194
}
195
```
196
197
### Control Panel Configuration
198
199
Configuration interface for chart customization in Superset.
200
201
```typescript { .api }
202
interface ControlPanelConfig {
203
controlPanelSections: ControlSection[];
204
controlOverrides: Record<string, any>;
205
formDataOverrides: (formData: any) => any;
206
}
207
208
interface ControlSection {
209
label: string;
210
expanded: boolean;
211
controlSetRows: ControlSetRow[];
212
}
213
214
type ControlSetRow = (string | ControlConfig)[];
215
216
interface ControlConfig {
217
name: string;
218
config: {
219
type: string;
220
label: string;
221
default?: any;
222
choices?: [string, string][];
223
options?: [string, string][];
224
description?: string;
225
renderTrigger?: boolean;
226
freeForm?: boolean;
227
visibility?: (state: any) => boolean;
228
};
229
}
230
```
231
232
### Color Mapping Utilities
233
234
Color mapping strategies and utilities for the chart.
235
236
```typescript { .api }
237
enum ColorBy {
238
metric = 'metric',
239
country = 'country'
240
}
241
```
242
243
### Core Types
244
245
Type definitions used throughout the plugin.
246
247
```typescript { .api }
248
interface SupersetTheme {
249
colors: {
250
grayscale: {
251
light2: string;
252
light5: string;
253
dark2: string;
254
};
255
};
256
}
257
258
enum Behavior {
259
DRILL_TO_DETAIL = 'DRILL_TO_DETAIL'
260
}
261
262
interface ChartPlugin {
263
constructor(config: {
264
loadChart: () => Promise<any>;
265
metadata: ChartMetadata;
266
transformProps: (props: any) => any;
267
controlPanel: ControlPanelConfig;
268
}): void;
269
}
270
```
271
272
## Configuration Options
273
274
### Country Field Types
275
276
The chart supports different country code formats:
277
278
- `'name'`: Full country names
279
- `'cioc'`: International Olympic Committee codes
280
- `'cca2'`: ISO 3166-1 alpha-2 codes (default)
281
- `'cca3'`: ISO 3166-1 alpha-3 codes
282
283
### Color Mapping
284
285
Two coloring strategies are supported:
286
287
- `'metric'`: Countries colored by primary metric values using sequential color schemes
288
- `'country'`: Countries colored categorically using distinct colors per country
289
290
### Bubble Overlays
291
292
When `showBubbles` is true, circular overlays are rendered on the map:
293
294
- Size determined by secondary metric (`m2`) values
295
- Color matches the base chart color
296
- Positioning based on country latitude/longitude coordinates
297
- Maximum size controlled by `maxBubbleSize` parameter
298
299
## Error Handling
300
301
The chart handles several error conditions:
302
303
- **Invalid country codes**: Countries with codes not found in the datamaps dataset are filtered out
304
- **Missing data**: Countries without data are rendered with default fill color
305
- **Context menu errors**: Invalid context menu interactions are logged with warnings
306
- **Right-click handling**: Malformed country data prevents context menu creation
307
308
## Usage Examples
309
310
### Basic Choropleth Map
311
312
```javascript
313
const formData = {
314
entity: 'country_code',
315
countryFieldtype: 'cca2',
316
colorBy: 'metric',
317
linearColorScheme: 'blues',
318
showBubbles: false
319
};
320
321
const data = [
322
{ country: 'US', name: 'United States', m1: 1000, m2: 500, latitude: 39.8, longitude: -98.6 },
323
{ country: 'CA', name: 'Canada', m1: 750, m2: 300, latitude: 56.1, longitude: -106.3 },
324
{ country: 'MX', name: 'Mexico', m1: 500, m2: 200, latitude: 23.6, longitude: -102.5 }
325
];
326
```
327
328
### Bubble Overlay Map
329
330
```javascript
331
const formData = {
332
entity: 'country_code',
333
countryFieldtype: 'cca3',
334
colorBy: 'country',
335
colorScheme: 'supersetColors',
336
showBubbles: true,
337
maxBubbleSize: 50
338
};
339
340
const data = [
341
{ country: 'USA', name: 'United States', m1: 1000, m2: 5000, latitude: 39.8, longitude: -98.6 },
342
{ country: 'CAN', name: 'Canada', m1: 750, m2: 3000, latitude: 56.1, longitude: -106.3 }
343
];
344
```
345
346
### Custom Color Configuration
347
348
```javascript
349
const formData = {
350
colorPicker: { r: 255, g: 0, b: 0 }, // Red base color
351
colorBy: 'metric',
352
linearColorScheme: 'reds'
353
};
354
```