This is a DEPRECATED VERSION of Web SDK.
Web SDK is a JavaScript library to create custom applications on top of CARTO, using deck.gl
DEPRECATION WARNING! This project won’t be continued. Due to feedback received from the users and to bring a better integration with deck.gl, we’re moving to a native deck.gl module. See @deck.gl/carto
In this guide, you will learn how to add interactivity to your application using highlighting and pop-ups. It is recommended to read first the Getting Started guide to understand the basic structure of a Web SDK application.
After completing this guide, you will know how to make your geospatial applications more interactive!
With the Web SDK it is very easy to highlight features. You can highlight a feature when the pointer moves over the feature and when the feature is clicked. You can specify one or both events and have a different style for each event.
We are going to start by highlighting the features when the pointer moves over them. In order to do that you must specify the hoverStyle parameter in the options object while creating the layer. You can specify different parameters like the color (fill), stroke color or stroke width. There is a default style that specifies light yellow as the stroke color, a slightly darker yellow as the stroke color and 5 as the stroke width. The options parameter is the third parameter to the Layer constructor so we need to specify also the style parameter. The highlighting is removed when we move the pointer out of the feature.
1
2
3
const countriesLayer = new carto.viz.Layer('ne_50m_admin_0_countries', carto.viz.style.basic(), {
hoverStyle: 'default'
});
View this step here
You can specify custom highlighting properties directly usings the deck.gl properties like getFillColor or getLineColor.
1
2
3
4
5
6
7
const countriesLayer = new carto.viz.Layer('ne_50m_admin_0_countries', carto.viz.style.basic(), {
hoverStyle: {
getFillColor: [0, 255, 255, 255],
getLineColor: [0, 220, 220, 255],
getLineWidth: 4
}
});
View this step here
If you want to highlight the features when the user clicks on them, you must use the clickStyle parameter. The options are the same for this parameter and the hoverStyle parameter. The highlighting is removed when we click on another feature.
1
2
3
4
5
6
7
const countriesLayer = new carto.viz.Layer('ne_50m_admin_0_countries', carto.viz.style.basic(), {
clickStyle: {
getFillColor: [0, 255, 255, 255],
getLineColor: [0, 220, 220, 255],
getLineWidth: 4
}
});
View this step here
You can apply both highlighting styles to the same layer. In this case we are going to use the default highlighting for the hoverStyle parameter and use a custom highlighting style for the clickStyle parameter.
1
2
3
4
5
6
7
8
const countriesLayer = new carto.viz.Layer('ne_50m_admin_0_countries', carto.viz.style.basic(), {
hoverStyle: 'default',
clickStyle: {
getFillColor: [0, 255, 255, 255],
getLineColor: [0, 220, 220, 255],
getLineWidth: 4
}
});
View this step here
The Web SDK allows you to add pop-ups both when the user moves the pointer over a feature and when the user clicks on a feature. You can add the pop-up by calling the setPopupHover or setPopupClick methods in the Layer object. You can call the methods before or after adding the layer to the map. You need to specify the attributes/feature properties that you want to show in the pop-up. For each attribute the Web SDK shows the attribute name (title) and the value. You can specify a different attribute name using the title property and you can apply a specific format for the value property.
Pop-ups use the Airship library, so you need to add the Airship CSS and JavaScript files to our page.
1
2
3
4
<!-- Include Airship from the CARTO CDN -->
<link rel="stylesheet" href="https://libs.cartocdn.com/airship-style/v2.4.0/airship.css">
<script type="module" src="https://libs.cartocdn.com/airship-components/v2.4.0/airship/airship.esm.js"></script>
<script nomodule="" src="https://libs.cartocdn.com/airship-components/v2.4.0/airship/airship.js"></script>
The addTo method in the Layer object and the setPopupHoverand setPopupClick are async functions. To be sure that you get the desired results when calling these methods, it is safer to called them using the await statement, inside another function defined as async.
1
2
3
4
5
6
async function initialize()
{
layer = new carto.viz.Layer(...);
await layer.addTo(...);
await layer.setPopupHover(...);
};
We are going to start by adding a pop-up when the user moves the pointer over a feature. We will show the country name and the estimated population. In addition to that, we are going to hide the name attribute title and show a more meaningful title for the pop_est attribute. The pop-up is hidden when you move the pointer out of the feature.
1
2
3
4
5
6
7
8
9
10
await countriesLayer.setPopupHover([
{
attr: 'name',
title: null
},
{
attr: 'pop_est',
title: 'Estimated Population'
}
]);
View this step here
Now we are going to add a pop-up when the user clicks on a feature. In this case we are going to add more attributes and apply some formatting for the numeric values. The pop-up is hidden when you click in another feature.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
await countriesLayer.setPopupClick([
{
attr: 'name',
title: null
},
{
attr: 'pop_est',
title: 'Estimated Population',
format: value => Math.round((value / 1.0e+6) * 100) / 100 + 'M inhabitants'
},
{
attr: 'economy',
title: 'Economy Group'
},
{
attr: 'income_grp',
title: 'Income Group'
}
]);
View this step here
Once you have added a pop-up for a layer, you can easily disable it by calling the pop-up function with a null argument.
1
2
await countriesLayer.setPopupHover(null);
await countriesLayer.setPopupClick(null);
This is the complete example with feature highlighting and pop-ups both for hover and click events on the features.
You can explore the final step here
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Interactivity and Pop-ups Guide - Step 7</title>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v1.10.0/mapbox-gl.css' rel='stylesheet' />
<link href="https://libs.cartocdn.com/airship-style/v2.4.0/airship.css" rel="stylesheet" >
<style>
body {
margin: 0;
padding: 0;
}
#map {
width: 100vw;
height: 100vh;
}
</style>
</head>
<body>
<div id="map"></div>
<!-- Include deck.gl from unpkg CDN -->
<script src="https://unpkg.com/deck.gl@8.2.0/dist.min.js"></script>
<!-- Include Mapbox GL from the Mabpox CDN -->
<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.10.0/mapbox-gl.js'></script>
<!-- Include Web SDK from the CARTO CDN -->
<script src="https://libs.cartocdn.com/web-sdk/v1.0.0-alpha.3/index.min.js"></script>
<!-- Include Airship from the CARTO CDN -->
<script type="module" src="https://libs.cartocdn.com/airship-components/v2.4.0/airship/airship.esm.js"></script>
<script nomodule="" src="https://libs.cartocdn.com/airship-components/v2.4.0/airship/airship.js"></script>
<script>
async function initialize()
{
carto.auth.setDefaultCredentials({ username: 'public' });
const deckMap = carto.viz.createMap();
const countriesLayer = new carto.viz.Layer('ne_50m_admin_0_countries', carto.viz.style.basic(), {
hoverStyle: 'default',
clickStyle: {
getFillColor: [0, 255, 255, 255],
getLineColor: [0, 220, 220, 255],
getLineWidth: 4
}
});
await countriesLayer.addTo(deckMap);
await countriesLayer.setPopupHover([
{
attr: 'name',
title: null
},
{
attr: 'pop_est',
title: 'Estimated Population'
}
]);
await countriesLayer.setPopupClick([
{
attr: 'name',
title: null
},
{
attr: 'pop_est',
title: 'Estimated Population',
format: value => Math.round((value / 1.0e+6) * 100) / 100 + 'M inhabitants'
},
{
attr: 'economy',
title: 'Economy Group'
},
{
attr: 'income_grp',
title: 'Income Group'
}
]);
}
initialize();
</script>
</body>
</html>