0
# Superset Legacy Plugin Chart Country Map
1
2
A legacy country map visualization plugin for Apache Superset that creates interactive choropleth-style maps for displaying geographical data across various countries and regions. This plugin enables users to visualize metrics across a country's principal subdivisions (states, provinces, etc.) with hover interactions and zoom capabilities.
3
4
## Package Information
5
6
- **Package Name**: @superset-ui/legacy-plugin-chart-country-map
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @superset-ui/legacy-plugin-chart-country-map`
10
11
## Core Imports
12
13
```javascript
14
import CountryMapChartPlugin, { countries } from "@superset-ui/legacy-plugin-chart-country-map";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const CountryMapChartPlugin = require("@superset-ui/legacy-plugin-chart-country-map").default;
21
const { countries } = require("@superset-ui/legacy-plugin-chart-country-map");
22
```
23
24
## Basic Usage
25
26
```javascript
27
import CountryMapChartPlugin from "@superset-ui/legacy-plugin-chart-country-map";
28
29
// Register the plugin with Superset
30
const plugin = new CountryMapChartPlugin();
31
32
// Access country mappings for configuration
33
import { countries } from "@superset-ui/legacy-plugin-chart-country-map";
34
console.log(countries.usa); // Returns USA GeoJSON data path
35
// For country options, you need to import directly from countries module
36
// or access via separate import since it's not re-exported from main index
37
```
38
39
## Architecture
40
41
The plugin follows Superset's chart plugin architecture:
42
43
- **Chart Plugin Class**: Main `CountryMapChartPlugin` that extends Superset's `ChartPlugin` base class
44
- **Chart Component**: D3-based visualization component (`CountryMap`) wrapped in React (`ReactCountryMap`)
45
- **Data Transformation**: `transformProps` function that converts Superset data format to chart props
46
- **Control Panel**: Configuration interface defining available chart options
47
- **Country Data**: Pre-loaded GeoJSON data for 62+ countries and regions
48
49
## Capabilities
50
51
### Chart Plugin Registration
52
53
Main plugin class for registering the country map visualization with Superset.
54
55
```javascript { .api }
56
/**
57
* Main chart plugin class for country map visualization
58
* Extends ChartPlugin from @superset-ui/core
59
*/
60
class CountryMapChartPlugin extends ChartPlugin {
61
constructor();
62
}
63
64
export default CountryMapChartPlugin;
65
```
66
67
### Country Data Access
68
69
Access to country mappings and configuration options for building country selection interfaces.
70
71
```javascript { .api }
72
/**
73
* Country mappings object - contains imported GeoJSON data for each supported country
74
* This is the countries object from countries.ts, re-exported as named export
75
*/
76
export const countries: Record<string, any>;
77
```
78
79
### Additional Utilities
80
81
For advanced usage, the countries module also exports additional utilities that are not re-exported from the main index:
82
83
```javascript { .api }
84
/**
85
* Array of [value, label] pairs for UI select controls
86
* Available as named export from '@superset-ui/legacy-plugin-chart-country-map/lib/countries'
87
* Generated from country keys with proper capitalization
88
*/
89
export const countryOptions: Array<[string, string]>;
90
```
91
92
### Chart Component Interface
93
94
The core chart component props interface (used internally by the plugin). Note: The actual implementation uses JavaScript with PropTypes validation, not TypeScript.
95
96
```javascript { .api }
97
/**
98
* Props interface for the CountryMap component (based on PropTypes)
99
*/
100
interface CountryMapProps {
101
/** Visualization data with country IDs and metrics */
102
data: Array<{
103
country_id: string;
104
metric: number;
105
}>;
106
/** Chart width in pixels */
107
width: number;
108
/** Chart height in pixels */
109
height: number;
110
/** Country identifier for map selection */
111
country: string;
112
/** Color scheme identifier for linear scaling */
113
linearColorScheme: string;
114
/** Number formatting specification */
115
numberFormat: string;
116
/** Base URL for map data (optional) */
117
mapBaseUrl?: string;
118
}
119
```
120
121
### Props Transformation
122
123
Transform function that converts Superset chart properties to component props.
124
125
```javascript { .api }
126
/**
127
* Transforms Superset chart properties to CountryMap component props
128
* @param chartProps - Raw chart properties from Superset
129
* @returns Transformed props for CountryMap component
130
*/
131
function transformProps(chartProps: ChartPropsConfig): CountryMapProps;
132
133
interface ChartPropsConfig {
134
width: number;
135
height: number;
136
formData: {
137
linearColorScheme: string;
138
numberFormat: string;
139
selectCountry: string;
140
colorScheme?: string;
141
sliceId?: string;
142
};
143
queriesData: Array<{
144
data: Array<{
145
country_id: string;
146
metric: number;
147
}>;
148
}>;
149
}
150
```
151
152
### Control Panel Configuration
153
154
Control panel configuration for chart customization in Superset UI.
155
156
```javascript { .api }
157
/**
158
* Control panel configuration object for Superset UI
159
*/
160
interface ControlPanelConfig {
161
controlPanelSections: Array<ControlSection>;
162
controlOverrides: Record<string, ControlOverride>;
163
}
164
165
interface ControlSection {
166
label: string;
167
expanded: boolean;
168
controlSetRows: Array<Array<string | ControlConfig>>;
169
tabOverride?: string;
170
}
171
172
interface ControlConfig {
173
name: string;
174
config: {
175
type: string;
176
label: string;
177
default?: any;
178
choices?: Array<[string, string]>;
179
description: string;
180
validators?: Array<Function>;
181
renderTrigger?: boolean;
182
freeForm?: boolean;
183
};
184
}
185
186
const controlPanel: ControlPanelConfig;
187
// Note: controlPanel is used internally by the plugin but not exported from main index
188
```
189
190
## Supported Countries
191
192
The plugin includes GeoJSON data for 62+ countries and regions:
193
194
- **Major Countries**: USA, China, India, Brazil, Germany, France, UK, Japan, Italy, Spain, Canada, Australia, Russia, etc.
195
- **European Countries**: Austria, Belgium, Bulgaria, Cyprus, Denmark, Estonia, Finland, Iceland, Lithuania, Netherlands, Norway, Poland, Portugal, Slovenia, Sweden, Switzerland, Ukraine
196
- **Asian Countries**: Indonesia, Iran, Jordan, Korea, Kuwait, Malaysia, Myanmar, Pakistan, Philippines, Singapore, Thailand, Vietnam
197
- **African Countries**: Egypt, Ethiopia, Kenya, Morocco, Nigeria, Rwanda, Tanzania, Uganda, Zambia, Burundi
198
- **Other Regions**: Mexico, Peru, Uruguay, Qatar, Saudi Arabia, United Arab Emirates, Oman, Syria, Liechtenstein, Timor-Leste
199
- **Special Regions**: Italy (regions) - separate regional view for Italy
200
201
## Chart Metadata
202
203
The plugin registers with the following metadata:
204
205
- **Category**: Map
206
- **Name**: Country Map
207
- **Description**: Visualizes how a single metric varies across a country's principal subdivisions on a choropleth map
208
- **Tags**: 2D, Comparison, Geo, Range, Report, Stacked
209
- **Legacy API**: Uses Superset's legacy API (`useLegacyApi: true`)
210
211
## Data Format
212
213
Input data should be formatted as an array of objects with:
214
215
```javascript { .api }
216
interface ChartDataPoint {
217
/** ISO 3166-2 code for the region/subdivision */
218
country_id: string;
219
/** Numeric value to visualize */
220
metric: number;
221
}
222
```
223
224
## Dependencies
225
226
### Runtime Dependencies
227
- `d3@^3.5.17` - D3.js library for data visualization
228
- `d3-array@^2.0.3` - D3 array utilities for data processing
229
- `prop-types@^15.6.2` - React prop types validation
230
231
### Peer Dependencies
232
- `@superset-ui/chart-controls@*` - Superset chart control components
233
- `@superset-ui/core@*` - Superset core utilities and base classes
234
235
## Features
236
237
- **Interactive Choropleth Maps**: Color-coded regions based on metric values
238
- **Hover Interactions**: Display region names and values on mouse hover
239
- **Click-to-Zoom**: Click regions to zoom in, click background to zoom out
240
- **Multiple Color Schemes**: Support for both linear and categorical color schemes
241
- **Flexible Formatting**: Configurable number formatting for metric display
242
- **Comprehensive Coverage**: Pre-loaded GeoJSON data for 62+ countries
243
- **Legacy Compatibility**: Maintains backward compatibility with existing Superset installations