6.8 KiB
Upgrade Considerations Guide
This document is intended for existing developers who have used previous versions of CARTO.js.
About this Guide
This guide describes how the CARTO.js library has changed to support additional functionality. It outlines the basic workflow for creating an application and includes an example of updating an old application using the new library.
Tip: The authorization system behaves in a uniform way for any version of CARTO.js. You can read about the fundamentals of authorization or know implementation details of the Auth API under the hood.
At a high-level, the workflow consists of:
-
Define the client parameters to manage layers and dataviews:
-
Define the Base data source objects:
- Add dataset as the source
carto.source.dataset - Add SQL to filter data
carto.source.sql
- Add dataset as the source
-
Publish the App:
You should understand the following changes in concept before you begin.
Dataset Privacy
Since we now have a new authorization system for the entire CARTO platform, directly related to dataset privacy, datasets can be public and private as well. Read the basics of authorization to learn more about this aspect of the CARTO platform.
Map Workflow
new carto.Client is the main entry point for building your application. This enables you to communicate between your app and your CARTO account by using your API Key. This enhancement clearly identifies client requests separate from visualization requests.
createVis
The current beta of CARTO.js only includes a JavaScript library, it does not include creatVis components to maintain your app. A future enhancement of the library will include functionality for maintaining your core application.
Dataview
A Dataview enables you to create different views of data stored in a table. CARTO.js uses Dataviews to add interactive widgets for viewing and filtering map data.
SQL API Integration
CARTO.js no longer includes a client for the SQL API. Developers looking to get data from their CARTO account can query SQL API with AJAX or the new JS Fetch API..
Upgrading an Existing Application
Suppose you have an app that was created with an earlier version of CARTO.js? This guide provides an example of CARTO.js components showing the old code modified with updated code.
The following example shows the application skeleton using version 3.15 of CARTO.js.
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="initial-scale=1.0" />
<meta charset="utf-8" />
<!-- include CartoDB.js CSS library -->
<link rel="stylesheet" href="http://libs.cartocdn.com/cartodb.js/v3/3.15/themes/css/cartodb.css" />
<!-- include CartoDB.js library -->
<script src="http://libs.cartocdn.com/cartodb.js/v3/3.15/cartodb.js"></script>
<style>
body {
margin: 0;
padding: 0;
}
#map {
position: absolute;
height: 100%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script>
const map = L.map('map').setView([30, 0], 3);
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
maxZoom: 18
}).addTo(map);
cartodb.createLayer(map, {
user_name: 'YOUR_USER_NAME',
type: 'cartodb',
sublayers: [
{
type: "mapnik",
sql: 'select * from populated_places_spf',
cartocss: '#populated_places_spf[adm0name = "Spain"]{ marker-fill: #fbb4ae; marker-allow-overlap: true;}#populated_places_spf[adm0name = "Portugal"]{ marker-fill: #ccebc5; marker-allow-overlap: true;}#populated_places_spf[adm0name = "France"]{ marker-fill: #b3cde3; marker-allow-overlap: true;}'
}
]
})
.addTo(map);
</script>
</body>
</html>
In order to make this example work with version 4 of CARTO.js, modify the code as follows:
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="initial-scale=1.0" />
<meta charset="utf-8" />
<!-- Include Leaflet -->
<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>
<link href="https://unpkg.com/leaflet/dist/leaflet.css" rel="stylesheet">
<!-- Include CARTO.js -->
<script src="https://cartodb-libs.global.ssl.fastly.net/carto.js/%VERSION%/carto.min.js"></script>
<style>
body {
margin: 0;
padding: 0;
}
#map {
position: absolute;
height: 100%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script>
const map = L.map('map').setView([30, 0], 3);
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
maxZoom: 18
}).addTo(map);
// define client
const client = new carto.Client({
apiKey: 'YOUR_API_KEY',
username: 'YOUR_USER_NAME'
});
// define source of data => dataset of your account
const source = new carto.source.Dataset(`populated_places_spf`);
// define CartoCSS code to style data on map
const style = new carto.style.CartoCSS(`
#layer[adm0name = "Spain"]{
marker-fill: #fbb4ae;
marker-allow-overlap: true;
}
#layer[adm0name = "Portugal"]{
marker-fill: #ccebc5;
marker-allow-overlap: true;
}
#layer[adm0name = "France"]{
marker-fill: #b3cde3;
marker-allow-overlap: true;
}`);
// create CARTO layer from source and style variables
const Cartolayer = new carto.layer.Layer(source, style);
// add CARTO layer to the client
client.addLayer(Cartolayer);
// get tile from client and add them to the map object
client.getLeafletLayer().addTo(map);
</script>
</body>
</html>
Conclusion
For more details about how to use CARTO.js, view the examples section for specific features of CARTO.js in action.