cartodb4/carto.js
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
zhongjin
2020-06-13 18:34:34 +08:00
commit 52aaa9f15d
655 changed files with 96796 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
docs/guides/01-overview.md Normal file
View File

@@ -0,0 +1,172 @@
## Overview
CARTO.js lets you create custom location intelligence applications that leverage the power of the CARTO Platform.
### Audience
This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. You should also be familiar with [Leaflet](https://leafletjs.com/) from a developer's point of view.
This conceptual documentation is designed to let you quickly start exploring and developing applications with the CARTO.js library. We also publish the [CARTO.js API Reference]({{site.cartojs_docs}}/reference/).
### Hello, World
The easiest way to start learning about the CARTO.js library is to see a simple example. The following web page displays a map adding a layer over it.
```html
<!DOCTYPE html>
<html>
<head>
<title>Single layer | CARTO</title>
<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://libs.cartocdn.com/carto.js/%VERSION%/carto.min.js"></script>
<link href="https://fonts.googleapis.com/css?family=Montserrat:600" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet">
<link href="https://carto.com/developers/carto-js/examples/maps/public/style.css" rel="stylesheet">
</head>
<body>
<div id="map">
</div>
<!-- Description -->
<aside class="toolbox">
<div class="box">
<header>
<h1>Add a layer</h1>
<button class="github-logo js-source-link"></button>
</header>
<section>
<p class="description open-sans">Add one CARTO layer to your map.</p>
</section>
<footer class="js-footer"></footer>
</div>
</aside>
<script>
const map = L.map('map').setView([30, 0], 3);
map.scrollWheelZoom.disable();
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
maxZoom: 18
}).addTo(map);
const client = new carto.Client({
apiKey: 'default_public',
username: 'cartojs-test'
});
const source = new carto.source.Dataset(`
ne_10m_populated_places_simple
`);
const style = new carto.style.CartoCSS(`
#layer {
marker-width: 7;
marker-fill: #EE4D5A;
marker-line-color: #FFFFFF;
}
`);
const layer = new carto.layer.Layer(source, style);
client.addLayer(layer);
client.getLeafletLayer().addTo(map);
</script>
</body>
</html>
```
[View example]({{site.cartojs_docs}}/examples/#example-add-a-layer).
Even in this simple example, there are a few things to note:
- We declare the application as HTML5 using the `<!DOCTYPE html>` declaration.
- We load the CARTO.js library using a `script` tag.
- We create a `div` element named "map" to hold the map.
- We define the JavaScript that creates a map in the `div`.
These steps are explained below.
### Declaring your application as HTML5
We recommend that you declare a true DOCTYPE within your web application. Within the examples here, we've declared our applications as HTML5 using the simple HTML5 DOCTYPE as shown below:
```html
<!DOCTYPE html>
```
Most current browsers will render content that is declared with this DOCTYPE in "standards mode" which means that your application should be more cross-browser compliant. The DOCTYPE is also designed to degrade gracefully; browsers that don't understand it will ignore it, and use "quirks mode" to display their content.
We add styles to the map through the file `style.css`, declaring:
```css
body {
margin: 0;
padding: 0;
}
#map {
position: absolute;
height: 100%;
width: 100%;
z-index: 0;
}
```
This CSS declaration indicates that the map container <div> (with id map) should take up 100% of the height of the HTML body.
### Loading the CARTO.js library
To load the Maps JavaScript API, use a script tag like the one in the following example:
```html
<script src="https://libs.cartocdn.com/carto.js/%VERSION%/carto.min.js"></script>
```
The URL contained in the script tag is the location of a JavaScript file that loads all of the code you need for using the CARTO.js library. This script tag is required. We are using the minified version of the library.
**Tip:** If you have experience with **npm** and a build system in your project (webpack, rollup…), you can install CARTO.js library with `npm install @carto/carto.js`. Then you can import it easily with `import carto from '@carto/carto.js` (or `var carto = require('@carto/carto.js')`, depending on your module system).
#### HTTPS or HTTP
We think security on the web is pretty important, and recommend using HTTPS whenever possible. As part of our efforts to make the web more secure, we've made all of the CARTO components available over HTTPS. Using HTTPS encryption makes your site more secure, and more resistant to snooping or tampering.
We recommend loading the CARTO.js library over HTTPS using the `<script>` tag provided above.
### Map DOM Elements
```html
<div id="map"></div>
```
For the map to display on a web page, we must reserve a spot for it. Commonly, we do this by creating a named div element and obtaining a reference to this element in the browser's document object model (DOM).
In the example above, we used CSS to set the height of the map div to "100%". This will expand to fit the size on mobile devices. You may need to adjust the width and height values based on the browser's screensize and padding.
### Map options
In this example, we are using Leaflet to render the map:
```javascript
const map = L.map('map').setView([30, 0], 3);
```
The common options for every map are: `center` and `zoom`. In this case, we are setting these with [Leaflet's setView method](https://leafletjs.com/reference-1.3.0.html#map-setview).
#### Zoom Levels
The initial resolution at which to display the map is set by the zoom property, where zoom 0 corresponds to a map of the Earth fully zoomed out, and larger zoom levels zoom in at a higher resolution. Specify zoom level as an integer. In our case, we are setting up this as **3**.
### Troubleshooting
If your code isn't working:
- Look for typos. Remember that JavaScript is a case-sensitive language.
- Check the basics. Some of the most common problems occur with the initial map creation. Such as:
- Confirm that you've specified the zoom and center properties in your map options.
- Ensure that you have declared a div element in which the map will appear on the screen.
- Ensure that the div element for the map has a height.
- Refer to our [examples]({{site.cartojs_docs}}/examples/) for a reference implementation.
- Use a JavaScript debugger to help identify problems. Chrome Developer Tools is a good one.
- Post questions to the [GIS Stack Exchange using the `CARTO` tag](https://gis.stackexchange.com/questions/tagged/carto). Guidelines on how to post great questions are available on the [support page]({{site.cartojs_docs}}/support/).

60
docs/guides/02-get-api-key.md Normal file
View File

@@ -0,0 +1,60 @@
## Get API Key
To use the CARTO.js library, you must register your project in your CARTO account and get an API key which you can add to your app or website.
### Quick guide to getting a key
#### Step 1: Get an API Key from your CARTO account
Start creating your API key, [registering a project](https://carto.com/login) in the CARTO Platform.
Notes:
- **Tip**: During development and testing, you can register a project for testing purposes in the CARTO Platform and use a generic, unrestricted API key. When you are ready to move your app or website into production, register a separate project for production, create a restricted API key, and add the key to your application.
- **Enterprise customers**: For production-ready apps, you must use a restricted API key.
For more information, see the [fundamentals about authorization]({{site.fundamental_docs}}/authorization/).
#### Step 2: Add the API key and username to your application
After loading the CARTO.js library, substitute YOUR_API_KEY in the code below with the API key you got from the previous step.
```javascript
var client = new carto.Client({
apiKey: '{YOUR_API_KEY}',
username: '{username}'
});
```
You can get your username following these steps:
- Login into to your CARTO account.
- Go to your account from the left menu.
- Copy the username under the plan information.
#### More about API keys
The API key allows you to control your applications in the CARTO Platform.
If you are a Trial Plan customer, with an API key you have access to all the Engine features.
If you are an Engine Plan customer, you must use an API key to access all the custom features and benefits of your Engine Plan.
#### Detailed guide for users of the CARTO.js library
Follow these steps to get an API key:
- Go to your CARTO account.
- Go to your API Keys dashboard.
- Click "NEW API KEY" to create a new one.
- If you want to manage projects, you can regenerate or delete them.
- On the API key page, configure it giving a name and the APIs and Datasets you want to use.
For more information on using the CARTO Platform, see our [fundamentals]({{site.fundamental_docs}}/).
#### Troubleshooting authorization issues
If your API key is malformed or you supply an invalid username, the CARTO.js library returns an HTTP 403 (Forbidden) error.
CARTO Enterprise customers have access to enterprise-level support through CARTO’s support representatives available at enterprise-support@carto.com.

408
docs/guides/03-quickstart.md Normal file
View File

@@ -0,0 +1,408 @@
## Quickstart Guide
CARTO.js lets you create custom location intelligence applications that leverage the power of the **[CARTO Engine](https://carto.com/pricing/engine/)** ecosystem.
This document details CARTO.js v4. To update your v3 apps, please consult the [Upgrade Considerations]({{site.cartojs_docs}}/guides/upgrade-considerations/).
### About this Guide
This guide describes how to create a Leaflet map and display data from CARTO over the map. This demonstrates how CARTO.js can be used to
1. Overlay Data from your CARTO account on any Map.
2. Use Dataviews to Create Widgets.
**Tip:** For more advanced documentation, view the [Full Reference API]({{site.cartojs_docs}}/reference/) or browse through some [examples]({{site.cartojs_docs}}/examples/). You can also read the [FAQs]({{site.cartojs_docs}}/support/faq/).
### Audience
This document is intended for website or mobile developers who want to include CARTO.js library within a webpage or mobile application. It provides an introduction to using the library and reference material on the available parameters.
### Requesting an API Key
CARTO.js requires using an API Key. From your CARTO dashboard, click [_Your API keys_](https://carto.com/login) from the avatar drop-down menu to view your uniquely generated API Key for managing data with CARTO Engine.
If you want learn more about authorization and authentication, read the [authorization fundamentals section]({{site.fundamental_docs}}/authorization/).
### Importing Datasets
Before you start working on the map, you need to import a couple of datasets. For this guide, we will use CARTO's Data Library, available from *Your datasets* dashboard, to import and connect public datasets to your account.
Alternatively, click the following links to download datasets from a public CARTO account:
* [European countries (ne_adm0_europe)](https://carto.com/dataset/ne_adm0_europe)
* [Populated places (ne_10m_populated_places_simple)](https://carto.com/dataset/ne_10m_populated_places_simple)
Once downloaded, import the datasets to your CARTO account.
### Setting up the Map
By the end of the lesson, you will have generated an HTML file of a Leaflet Map showing CARTO's Voyager basemap and labels on top.
#### Application Skeleton
Create an HTML file using your preferred text editor and paste the following code to build the application skeleton:
```html
<!DOCTYPE html>
<html>
<head>
<title>Guide | CARTO</title>
<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>
<!-- Fonts -->
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700" rel="stylesheet" type="text/css">
<style>
* { margin:0; padding:0; }
html { box-sizing:border-box; height:100%; }
body { background:#f2f6f9; height:100%; font-family:"Open sans", Helvetica, Arial, sans-serif; }
#container { display:flex; width:100%; height:100%; }
#map { flex:1; margin:10px; }
#widgets { width:300px; margin:10px 10px 10px 0; }
.widget { background:white; padding:10px; margin-bottom:10px; }
.widget h1 { font-size:1.2em; }
.widget-formula .result { font-size:2em; }
</style>
</head>
<body>
<div id="container">
<div id="map"></div>
<div id="widgets">
<div id="countriesWidget" class="widget">
<h1>European countries</h1>
<select class="js-countries">
<option value="">All</option>
</select>
</div>
<div id="avgPopulationWidget" class="widget widget-formula">
<h1>Average population</h1>
<p><span class="js-average-population result">xxx</span> inhabitants</p>
</div>
</div>
</div>
<script>
// code will go here!
</script>
</body>
</html>
```
The first part of the skeleton loads CARTO.js and Leaflet 1.2.0 assumes Leaflet is loaded in `window.L`. The library checks if the version of Leaflet is compatible. If not, it throws an error.
The app skeleton also loads CARTO.js, adds some necessary elements, and defines a `script` tag. This is where you will write all the JavaScript code to make the example work.
**Note:** While CARTO.js enables you to display data from CARTO on top of Leaflet or Google Maps map, the actual map settings are controlled via the [Leaflet](http://leafletjs.com/) or [Google Maps](https://hpneo.github.io/gmaps/) map options.
#### Creating the Leaflet Map
CARTO.js apps start from a Leaflet or Google Map. Let's use a basic [Leaflet](http://leafletjs.com/) map for this guide:
```javascript
const map = L.map('map').setView([50, 15], 4);
```
#### Adding Basemap and Label Layers
Define the type of basemap to be used for the background of your map. For this guide, let's use [CARTO's Voyager basemap](https://carto.com/location-data-services/basemaps/).
```javascript
// Adding Voyager Basemap
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
maxZoom: 18
}).addTo(map);
// Adding Voyager Labels
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png', {
maxZoom: 18,
zIndex: 10
}).addTo(map);
```
`L.tileLayer` creates a layer for the basemap and the `zIndex` property defines the basemap labels (that sit on top of the other layers).
### Defining a `carto.Client`
`carto.Client` is the entry point to CARTO.js. It handles the communication between your app and your CARTO account, which is defined by your API Key and your username.
```javascript
var client = new carto.Client({
apiKey: '{API Key}',
username: '{username}'
});
```
**Warning:** Ensure that you modify any placeholder parameters shown in curly brackets with your own credentials. For example, `apiKey: '123abc',` and `username: 'john123'`.
### Displaying Data on the Map
Display data hosted on your CARTO account as map layers.
### Defining Layers
Layers are defined with `carto.layer.Layer` which include the dataset name and basic styling options with CartoCSS.
```javascript
const europeanCountriesDataset = new carto.source.Dataset(`
ne_adm0_europe
`);
const europeanCountriesStyle = new carto.style.CartoCSS(`
#layer {
polygon-fill: #162945;
polygon-opacity: 0.5;
::outline {
line-width: 1;
line-color: #FFFFFF;
line-opacity: 0.5;
}
}
`);
const europeanCountries = new carto.layer.Layer(europeanCountriesDataset, europeanCountriesStyle);
```
The first layer defines a `carto.source.Dataset` object that points to the imported dataset named `ne_adm0_europe`. To style the layer, define a `carto.style.CartoCSS` object that describes how polygons will be rendered.
```javascript
const populatedPlacesSource = new carto.source.SQL(`
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name IN (SELECT admin FROM ne_adm0_europe)
`);
const populatedPlacesStyle = new carto.style.CartoCSS(`
#layer {
marker-width: 8;
marker-fill: #FF583E;
marker-fill-opacity: 0.9;
marker-line-width: 0.5;
marker-line-color: #FFFFFF;
marker-line-opacity: 1;
marker-type: ellipse;
marker-allow-overlap: false;
}
`);
const populatedPlaces = new carto.layer.Layer(populatedPlacesSource, populatedPlacesStyle, {
featureOverColumns: ['name']
});
```
The second layer uses a more complex type of data source for the layer. `carto.source.SQL` provides more flexibility for defining the data that you want to display in a layer. For this guide, we are composing a `SELECT` statement that selects populated cities in Europe. (Optionally, you can change this query at runtime).
The `featureOverColumns: ['name']` option we include in the layer creation defines what columns of the datasource will be available in `featureOver` events as we explain below.
#### Adding Layers to the Client
Before you can add layers to the map, the `carto.Client` variable needs to be notified that these layers exist. The client is responsible for grouping layers into a single Leaflet layer.
```javascript
client.addLayers([europeanCountries, populatedPlaces]);
```
#### Adding Layers to the Map
Now that the client recognizes these two layers, this single Leaflet layer can be added to the map.
```javascript
client.getLeafletLayer().addTo(map);
```
As a result, your map should display polygons for each European country and red points represent populated cities.
**Tip:** In order to change the order of layers, flip the order from `([A, B]);` to `(B, A);`
### Setting up Tooltips
Tooltips give map viewers information about the underlying data as they interact with the map by clicking or hovering over data. CARTO.js provides a simple mechanism to detect some of these interactions and use the data associated to them. For this guide, let's display a mouse hover tooltip showing the name of a city.
#### Showing the Tooltip when User Mouses Over a City
Layers trigger `featureOver` events when the map viewer hovers the mouse over a feature. The event includes data about the feature, such as the latitude and longitude, as well as specified column values defined in `featureOverColumns`.
```javascript
const popup = L.popup({ closeButton: false });
populatedPlaces.on(carto.layer.events.FEATURE_OVER, featureEvent => {
popup.setLatLng(featureEvent.latLng);
if (!popup.isOpen()) {
popup.setContent(featureEvent.data.name);
popup.openOn(map);
}
});
```
In this snippet, we are defining a `L.popup` and listening to the `featureOver` event. When the event is triggered, the pop-up is positioned, populated with the name of the city, and added to the map.
#### Hiding the Tooltip
Similarly, layers trigger `featureOut` events when the map viewer is no longer moving the mouse over a feature. Use this event to hide the pop-up.
```javascript
populatedPlaces.on(carto.layer.events.FEATURE_OUT, featureEvent => {
popup.removeFrom(map);
});
```
When `featureOut` is triggered, this code removes the pop-up from the map.
### Creating a Country Selector Widget
This section describes how to get data from a previously defined data source and display a country selector the map. As a result, selecting a country on the map highlights the country and filters by populated places.
#### Defining a Category Dataview
Dataviews are the mechanism CARTO.js uses to access data from a data source (dataset or SQL query) in a particular way (eg: list of categories, result of a formula, etc.). Use the `carto.dataview.Category` dataview to get the names of the European countries in the dataset:
```javascript
const countriesDataview = new carto.dataview.Category(europeanCountriesDataset, 'admin', {
limit: 100
});
```
This type of dataview expects a data source and the name of the column with the categories. By default, results are limited. For this guide, we specified a limit of 100 categories to make sure all country names are returned.
#### Listening to Data Changes on the Dataview
In order to know when a dataview has new data (eg: right after it has been added to the client or when its source has changed), you should listen to the `dataChanged` event. This event gives you an object with all the categories.
```javascript
countriesDataview.on('dataChanged', data => {
const countryNames = data.categories.map(category => category.name).sort();
refreshCountriesWidget(countryNames);
});
function refreshCountriesWidget(adminNames) {
const widgetDom = document.querySelector('#countriesWidget');
const countriesDom = widgetDom.querySelector('.js-countries');
countriesDom.onchange = event => {
const admin = event.target.value;
highlightCountry(admin);
filterPopulatedPlacesByCountry(admin);
};
// Fill in the list of countries
adminNames.forEach(admin => {
const option = document.createElement('option');
option.innerHTML = admin;
option.value = admin;
countriesDom.appendChild(option);
});
}
function highlightCountry(admin) {
let cartoCSS = `
#layer {
polygon-fill: #162945;
polygon-opacity: 0.5;
::outline {
line-width: 1;
line-color: #FFFFFF;
line-opacity: 0.5;
}
}
`;
if (admin) {
cartoCSS = `
${cartoCSS}
#layer[admin!='${admin}'] {
polygon-fill: #CDCDCD;
}
`;
}
europeanCountriesStyle.setContent(cartoCSS);
}
function filterPopulatedPlacesByCountry(admin) {
let query = `
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name IN (SELECT admin FROM ne_adm0_europe)
`;
if (admin) {
query = `
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name='${admin}'
`;
}
populatedPlacesSource.setQuery(query);
}
```
This snippet generates the list of country names in alphabetical order from the `dataChanged` parameter and uses the `SELECT` function to populate the list.
When a country is selected, two functions are invoked: `highlightCountry` (highlights the selected country by setting a new CartoCSS to the layer) and `filterPopulatedPlacesByCountry` (filters the cities by changing the SQL query).
#### Adding the Dataview to the Client
The dataview needs to be added to the client in order to fetch data from CARTO.
```javascript
client.addDataview(countriesDataview);
```
### Creating a Formula Widget
Now that you have a working country selector, let's add a widget that will display the average max population of the populated places for the selected country (or display ALL if no country is selected).
#### Defining a Formula Dataview
`carto.dataview.Formula` allows you to execute aggregate functions (count, sum, average, max, min) on a data source:
```javascript
const averagePopulation = new carto.dataview.Formula(populatedPlacesSource, 'pop_max', {
operation: carto.operation.AVG
});
```
The `averagePopulation` dataview triggers a `dataChanged` event every time a new average has been calculated.
#### Listening to Data Changes on the Dataview
The `dataChanged` event allows you to get results of the aggregate function and use it in many ways.
```javascript
averagePopulation.on('dataChanged', data => {
refreshAveragePopulationWidget(data.result);
});
function refreshAveragePopulationWidget(avgPopulation) {
const widgetDom = document.querySelector('#avgPopulationWidget');
const averagePopulationDom = widgetDom.querySelector('.js-average-population');
averagePopulationDom.innerText = Math.floor(avgPopulation);
}
```
This snippet refreshes the averaged population widget every time a new average is available (e.g., when a new country is selected).
#### Adding the dataview to the client
To get a full working dataview, add it to your client:
```javascript
client.addDataview(averagePopulation);
```
### Conclusion
<div class="example-map">
<iframe src="{{site.cartojs_docs}}/guides/quickstart-example.html" width="100%" height="600" frameBorder="0" style="padding-top: 20px;padding-bottom: 0;" class="u-vspace--24"></iframe>
<a href="{{site.cartojs_docs}}/guides/quickstart-example.html" class="buttonLink is-DocsGreen u-vspace--32" target="_blank">
<svg width="8px" height="7px" viewbox="0 0 8 7" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
<path class="buttonLink-media" d="M1.52245273,3.04854764 L3.68776506,0.883235307 C3.88225492,0.688745449 3.88821988,0.353713791 3.68525771,0.15075162 C3.4882313,-0.0462747862 3.15435142,-0.053333131 2.95277402,0.148244267 L0.147793654,2.95322464 C0.0109867585,3.09003153 -0.0325396573,3.29637729 0.0243152648,3.47738142 C-0.0325396573,3.65838554 0.0109867585,3.8647313 0.147793654,4.00153819 L2.95277402,6.80651857 C3.15435142,7.00809596 3.4882313,7.00103762 3.68525771,6.80401121 C3.88821988,6.60104904 3.88225492,6.26601738 3.68776506,6.07152753 L1.70421948,4.08798194 L7.99996393,4.08798194 L7.99996393,3.04854764 L1.52245273,3.04854764 Z" id="Combined-Shape" fill="#1FAC06" transform="translate(3.999982, 3.477381) scale(-1, 1) translate(-3.999982, -3.477381) "/>
</g>
</svg>
Click to open map full size
</a>
</div>
### Troubleshooting and support
For more information on using the CARTO.js library, take a look at the [support page]({{site.cartojs_docs}}/support/).
The CARTO.js library may issue an error or warning when something goes wrong. You should check for warnings in particular if you notice that something is missing. It's also a good idea to check for warnings before launching a new application. Note that the warnings may not be immediately apparent because they appear in the HTTP header. For more information, see the guide to [errors messages]({{site.cartojs_docs}}/support/error-messages/).
This guide is just an overview of how to use CARTO.js to overlay data and create widgets. View the [Examples]({{ site.cartojs_docs }}/examples/) section for specific features of CARTO.js in action.

101
docs/guides/04-performance-tips.md Normal file
View File

@@ -0,0 +1,101 @@
## Performance Tips
As you go through developing your applications with CARTO.js, you might find useful some tips to ease the development and make your application more performant.
### Sources
Sources are the objects to get data from. The source is the entity that points to the data we want to show in our layers or in a widget through a dataview.
When working with sources, you may want to change the actual query to show other data in your visualization or dataviews. The most common case is filtering your data. The layers and dataviews react to changes coming from linked sources, so that you don't have to create another source. Layers and dataviews that are linked to the source reflect the changes in the source.
The way to go is to call `.setQuery` method to update the SQL query when using a `carto.source.SQL`, or use `.setTableName` in a `carto.source.Dataset` source, like in this examples:
``` js
const populationSource = new carto.source.SQL('SELECT * FROM your_dataset');
populationSource.setQuery('SELECT * FROM your_dataset WHERE price < 80');
```
![setQuery diagram](../../img/set_query_diagram.svg)
``` js
const populationDataset = new carto.source.Dataset('your_dataset');
populationDataset.setTableName('another_dataset');
```
![setTableName diagram](../../img/set_table_name_diagram.svg)
That way, the dataviews and visualizations retrieving data from that source will be automatically updated without doing anything else on your part.
### Styles
We need to use CartoCSS whenever we want to change the style of our markers or polygons, among other things. Each CartoCSS instance contains the styles we want to apply to any of our layers.
These style instances work the same way as sources do. It is pretty common to change styles in your map based on certain triggers, so that you can adequate your visualization to what you want to show.
When linked to a layer, it will automatically show the style change when invoking `.setContent` on the style object with a string containing the new style content.
```js
const layerStyle = new carto.style.CartoCSS(`
#layer {
marker-width: 8;
marker-fill: #FF583E;
marker-fill-opacity: 0.9;
marker-allow-overlap: false;
}
`);
layerStyle.setContent(`
#layer {
marker-width: 10;
marker-fill: #FF583E;
marker-allow-overlap: true;
}
`);
```
![setContent diagram](../../img/set_content_diagram.svg)
### Layers
Layers are a fundamental part of your CARTO.js application. They show the data of a source using the style of a CartoCSS.
As stated before, the layer will be automatically updated in the map when any of its properties (source and style) change.
So, let's say that you want to update the table of your visualization which had been created like this:
``` js
const populationSource = new carto.source.SQL('SELECT * FROM your_dataset');
const layerStyle = new carto.style.CartoCSS(`
#layer {
marker-width: 10;
marker-fill: #FF583E;
marker-allow-overlap: true;
}
`);
const layer = new carto.layer.Layer(populationSource, layerStyle);
```
To update the visualization, the only thing you need to do is to invoke `.setQuery` in your source and everything will be refreshed accordingly.
```js
populationSource.setQuery('SELECT * FROM your_dataset WHERE price > 500');
```
### Dataviews
Dataviews are a way to extract data from our source in predefined ways depending on the type of the column (eg: a list of categories, the result of a formula operation, etc...).
Dataviews need a source to extract data from. So when a source is passed to a dataview, it will react to the changes happening to the source, whether changing the query or adding filters.
```js
const populatedPlaces = new carto.source.Dataset('ne_10m_populated_places_simple');
const column = 'adm0name'; // Aggregate the data by country.
const categoryDataview = new carto.dataview.Category(populatedPlaces, column, {
operation: carto.operation.AVG, // Compute the average
operationColumn: 'pop_max' // The name of the column where the operation will be applied.
});
// ...
citiesSource.addFilter(new carto.filter.Category(column, { eq: 'Spain' } ));
```
In the example above, first we set a dataview getting data from a dataset with information about populated places. Then, we add a filter to the source to show only data coming from Spain. As you can see, we've updated the source and since the dataview was created linked to that source, a change on the query makes the dataview to react to that change automatically. There's no need to create another source and then another dataview.

181
docs/guides/05-upgrade-considerations.md Normal file
View File

@@ -0,0 +1,181 @@
## Upgrade Considerations Guide
This document is intended for existing developers who have used [previous versions]({{site.cartojs_docs}}/reference/#versioning) 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]({{site.fundamental_docs}}/authorization/) or know implementation details of the [Auth API]({{site.authapi_docs}}/) under the hood.
At a high-level, the workflow consists of:
1. Define the client parameters to manage layers and dataviews:
- [`new carto.Client`]({{site.cartojs_docs}}/reference/#cartoclient)
- [`addLayers`]({{site.cartojs_docs}}/reference/#cartoclientaddlayer)
- [`addDataview`]({{site.cartojs_docs}}/reference/#cartoclientadddataview) or [`addDataviews`]({{site.cartojs_docs}}/reference/#cartoclientadddataviews)
- [`getDataviews`]({{site.cartojs_docs}}/reference/#cartoclientgetdataviews)
2. Define the Base data source objects:
- Add dataset as the source [`carto.source.dataset`]({{site.cartojs_docs}}/reference/#cartosourcedataset)
- Add SQL to filter data [`carto.source.sql`]({{site.cartojs_docs}}/reference/#cartosourcesql)
3. Publish the App:
- [`getLayers`]({{site.cartojs_docs}}/reference/#cartoclientgetlayers)
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]({{site.fundamental_docs}}/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](https://developer.mozilla.org/en-US/docs/Web/API/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.
```html
<!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:
```html
<!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]({{site.cartojs_docs}}/examples/) section for specific features of CARTO.js in action.

35
docs/guides/06-glossary.md Normal file
View File

@@ -0,0 +1,35 @@
## Glossary
This glossary defines terms that appear throughout the CARTO.js documentation.
### A
#### Ajax
Asynchronous JavaScript + XML, while not a technology in itself, is a term coined in 2005 by Jesse James Garrett, that describes a "new" approach to using a number of existing technologies together, including HTML or XHTML, Cascading Style Sheets, JavaScript, The Document Object Model, XML, XSLT, and most importantly the XMLHttpRequest object. More info about Ajax at [Ajax](https://developer.mozilla.org/en-US/docs/Web/Guide/AJAX).
### C
#### Client
Throughout CARTO.js documentation, `client` refers to the object used as an entry point to CARTO.js features.
It's the object used to add your account credentials and to manage layers and dataviews.
More info at [carto.Client]({{site.cartojs_docs}}/reference/#cartoclient)
### L
#### Layer
A layer object is used to visualize geospatial data in CARTO.js. They have a source, where the data comes from, and a style, defining how you want the layer to look like.
They are showed on top of a Leaflet or a Google map.
[Layer reference]({{site.cartojs_docs}}/reference/#cartolayerlayer)
### P
#### Promise
Promise objects are a standard way for handling asynchronous tasks in Javascript. More info about promises at [Using Promises - MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises).

203
docs/guides/quickstart-example.html Normal file
View File

@@ -0,0 +1,203 @@
<!DOCTYPE html>
<html>
<head>
<title>Guide | CARTO</title>
<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>
<!-- Fonts -->
<link href='https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700' rel='stylesheet' type='text/css'>
<style>
* { margin:0; padding:0; }
html { box-sizing:border-box; height:100%; }
body { background:#f2f6f9; height:100%; font-family:"Open sans", Helvetica, Arial, sans-serif; }
#container { display:flex; width:100%; height:100%; }
#map { flex:1; margin:10px; }
#widgets { width:300px; margin:10px 10px 10px 0; }
.widget { background:white; padding:10px; margin-bottom:10px; }
.widget h1 { font-size:1.2em; }
.widget-formula .result { font-size:2em; }
</style>
</head>
<body>
<div id="container">
<div id="map"></div>
<div id="widgets">
<div id="countriesWidget" class="widget">
<h1>European countries</h1>
<select class="js-countries">
<option value="">All</option>
</select>
</div>
<div id="avgPopulationWidget" class="widget widget-formula">
<h1>Average population</h1>
<p><span class="js-average-population result">xxx</span> inhabitants</p>
</div>
</div>
</div>
<script>
const map = L.map('map').setView([50, 15], 4);
// Adding Voyager Basemap
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
maxZoom: 18
}).addTo(map);
// Adding Voyager Labels
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png', {
maxZoom: 18,
zIndex: 10
}).addTo(map);
var client = new carto.Client({
apiKey: 'default_public',
username: 'cartojs-test'
});
const europeanCountriesDataset = new carto.source.Dataset(`
ne_adm0_europe
`);
const europeanCountriesStyle = new carto.style.CartoCSS(`
#layer {
polygon-fill: #162945;
polygon-opacity: 0.5;
::outline {
line-width: 1;
line-color: #FFFFFF;
line-opacity: 0.5;
}
}
`);
const europeanCountries = new carto.layer.Layer(europeanCountriesDataset, europeanCountriesStyle);
const populatedPlacesSource = new carto.source.SQL(`
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name IN (SELECT admin FROM ne_adm0_europe)
`);
const populatedPlacesStyle = new carto.style.CartoCSS(`
#layer {
marker-width: 8;
marker-fill: #FF583E;
marker-fill-opacity: 0.9;
marker-line-width: 0.5;
marker-line-color: #FFFFFF;
marker-line-opacity: 1;
marker-type: ellipse;
marker-allow-overlap: false;
}
`);
const populatedPlaces = new carto.layer.Layer(populatedPlacesSource, populatedPlacesStyle, {
featureOverColumns: ['name']
});
client.addLayers([europeanCountries, populatedPlaces]);
client.getLeafletLayer().addTo(map);
const popup = L.popup({ closeButton: false });
populatedPlaces.on(carto.layer.events.FEATURE_OVER, featureEvent => {
popup.setLatLng(featureEvent.latLng);
if (!popup.isOpen()) {
popup.setContent(featureEvent.data.name);
popup.openOn(map);
}
});
populatedPlaces.on(carto.layer.events.FEATURE_OUT, featureEvent => {
popup.removeFrom(map);
});
const averagePopulation = new carto.dataview.Formula(populatedPlacesSource, 'pop_max', {
operation: carto.operation.AVG
});
averagePopulation.on('dataChanged', data => {
refreshAveragePopulationWidget(data.result);
});
function refreshAveragePopulationWidget(avgPopulation) {
const widgetDom = document.querySelector('#avgPopulationWidget');
const averagePopulationDom = widgetDom.querySelector('.js-average-population');
averagePopulationDom.innerText = Math.floor(avgPopulation);
}
client.addDataview(averagePopulation);
const countriesDataview = new carto.dataview.Category(europeanCountriesDataset, 'admin', {
limit: 100
});
countriesDataview.on('dataChanged', data => {
const countryNames = data.categories.map(category => category.name).sort();
refreshCountriesWidget(countryNames);
});
function refreshCountriesWidget(adminNames) {
const widgetDom = document.querySelector('#countriesWidget');
const countriesDom = widgetDom.querySelector('.js-countries');
countriesDom.onchange = event => {
const admin = event.target.value;
highlightCountry(admin);
filterPopulatedPlacesByCountry(admin);
};
// Fill in the list of countries
adminNames.forEach(admin => {
const option = document.createElement('option');
option.innerHTML = admin;
option.value = admin;
countriesDom.appendChild(option);
});
}
function highlightCountry(admin) {
let cartoCSS = `
#layer {
polygon-fill: #162945;
polygon-opacity: 0.5;
::outline {
line-width: 1;
line-color: #FFFFFF;
line-opacity: 0.5;
}
}
`;
if (admin) {
cartoCSS = `
${cartoCSS}
#layer[admin!='${admin}'] {
polygon-fill: #CDCDCD;
}
`;
}
europeanCountriesStyle.setContent(cartoCSS);
}
function filterPopulatedPlacesByCountry(admin) {
let query = `
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name IN (SELECT admin FROM ne_adm0_europe)
`;
if (admin) {
query = `
SELECT *
FROM ne_10m_populated_places_simple
WHERE adm0name='${admin}'
`;
}
populatedPlacesSource.setQuery(query);
}
client.addDataview(countriesDataview);
</script>
</body>
</html>

BIN
docs/img/avatar.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 187 KiB

19
docs/img/set_content_diagram.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

21
docs/img/set_query_diagram.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

21
docs/img/set_table_name_diagram.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

9
docs/reference/01-introduction.md Normal file
View File

@@ -0,0 +1,9 @@
## Introduction
CARTO.js is a JavaScript library that interacts with different CARTO APIs. It is part of the [CARTO Engine](https://carto.com/pricing/engine/) ecosystem.
To understand the fundamentals of CARTO.js v4, [read the guides]({{site.cartojs_docs}}/guides/quickstart/). To view the source code, browse the [open-source repository](https://github.com/CartoDB/carto.js) in Github and contribute. Otherwise, view [examples with Leaflet and Google Maps]({{site.cartojs_docs}}/examples/) or find different [support options]({site.cartojs_docs}}/support/support-options/).
If you find any trouble understanding any term written in this reference, please visit our [glossary]({{site.cartojs_docs}}/guides/glossary/)
The contents described in this document are subject to CARTO's [Terms of Service](https://carto.com/legal/)

16
docs/reference/02-authentication.md Normal file
View File

@@ -0,0 +1,16 @@
## Authentication
CARTO.js v4 requires using an API Key. From your CARTO dashboard, click _[Your API keys](https://carto.com/login)_ from the avatar drop-down menu to view your uniquely generated API Key for managing data with CARTO Engine.
![Your API Keys](../img/avatar.gif)
Learn more about the [basics of authorization]({{site.fundamental_docs}}/authorization/), or dig into the details of [Auth API]({{site.authapi_docs}}/), if you want to know more about this part of CARTO platform.
The examples in this documentation include a placeholder for the API Key. Ensure that you modify any placeholder parameters with your own credentials. You will have to supply your unique API Key to a [`carto.Client`](#cartoclient).
```javascript
var client = new carto.Client({
apiKey: 'YOUR_API_KEY_HERE',
username: 'YOUR_USERNAME_HERE'
});
```

10
docs/reference/03-versioning.md Normal file
View File

@@ -0,0 +1,10 @@
## Versioning
CARTO.js uses [Semantic Versioning](http://semver.org/). View our Github repository to find tags for each [release](https://github.com/CartoDB/carto.js/releases).
To get the version number programmatically, use `carto.version`.
```javascript
console.log(carto.version);
// returns the version of the library
```

20
docs/reference/04-loading-the-library.md Normal file
View File

@@ -0,0 +1,20 @@
## Loading the Library
CARTO.js is hosted on a CDN for easy loading. You can load the full source "carto.js" file or the minified version "carto.min.js". Once the script is loaded, you will have a global `carto` namespace.
CARTO.js is hosted in NPM as well. You can require it as a dependency in your custom apps.
```html
<!-- CDN: load the latest CARTO.js version -->
<script src="https://libs.cartocdn.com/carto.js/%CURRENT_VERSION%/carto.min.js"></script>
<!-- CDN: load a specific CARTO.js version-->
<script src="https://libs.cartocdn.com/carto.js/%VERSION%/carto.min.js"></script>
```
```javascript
// NPM: load the latest CARTO.js version
npm install @carto/carto.js
// or
yarn add @carto/carto.js
var carto = require('@carto/carto.js');
```

20
docs/reference/05-error-handling.md Normal file
View File

@@ -0,0 +1,20 @@
## Error Handling
Most of the errors fired by the library are handled by the client itself. The client will trigger a `CartoError` every time an error happens.
A cartoError is an object containing a single `message` field with a string explaining the error.
Some methods in CARTO.js are asynchronous. This means that they return a promise that will be fulfilled when the asynchronous work is done or rejected with a `CartoError` when an error occurs.
```javascript
// All errors are passed to the client.
client.on(carto.events.ERROR, cartoError => {
console.error(cartoError.message):
})
// .addLayer() is async.
client.addLayer(newLayer)
.then(successCallback)
.catch(errorCallback);
```

38
docs/support/01-support-options.md Normal file
View File

@@ -0,0 +1,38 @@
## Support Options
Feeling stuck? There are many ways to find help.
* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
* [Report an issue](https://github.com/CartoDB/carto.js/issues) in Github.
* Enterprise Plan customers have additional access to enterprise-level support through CARTO's support representatives.
If you just want to describe an issue or share an idea, just <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank"> send your feedback</a><script>(function() { var qs,js,q,s,d=document, gi=d.getElementById, ce=d.createElement, gt=d.getElementsByTagName, id="typef_orm_share", b="https://embed.typeform.com/"; if(!gi.call(d,id)){ js=ce.call(d,"script"); js.id=id; js.src=b+"embed.js"; q=gt.call(d,"script")[0]; q.parentNode.insertBefore(js,q) } })() </script>.
### Issues on Github
If you think you may have found a bug, or if you have a feature request that you would like to share with the CARTO.js team, please [open an issue](https://github.com/cartodb/carto.js/issues/new).
Before opening an issue, review the [contributing guidelines](https://github.com/CartoDB/carto.js/blob/develop/CONTRIBUTING.md#filling-a-ticket).
### Community support on GIS Stack Exchange
GIS Stack Exchange is the most popular community in the geospatial industry. This is a collaboratively-edited question and answer site for geospatial programmers and technicians. It is a fantastic resource for asking technical questions about developing and maintaining your application.
Members of the CARTO.js team regularly monitor the `carto` tag. You can look for CARTO topics by adding `carto` or `carto.js` to your search query. You can also add additional tags to your question in order to attract the attention of experts in related technologies.
When posting a new question, please consider the following:
* Read the GIS Stack Exchange [help](https://gis.stackexchange.com/help) and [how to ask](https://gis.stackexchange.com/help/how-to-ask) pages for guidelines and tips about posting questions.
* Be very clear about your question in the subject. A clear explanation helps those trying to answer your question, as well as those who may be looking for information in the future.
* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem.
* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem.
### Enterprise Plan Customers
Enterprise Plan customers have additional support options beyond general community support. As per your account Terms of Service, you have access to enterprise-level support through CARTO's support representatives available at [enterprise-support@carto.com](mailto:enterprise-support@carto.com)
In order to speed up the resolution of your issue, provide as much information as possible (even if it is a link from community support). This allows our engineers to investigate your problem as soon as possible.
If you are not yet CARTO customer, browse our [plans & pricing](https://carto.com/pricing/) and find the right plan for you.

51
docs/support/02-faq.md Normal file
View File

@@ -0,0 +1,51 @@
## FAQs
CARTO.js v4 introduces new concepts that in some cases, change the behavior of old components. This section clarifies those changes and describe new functionality.
### Do I need an API Key?
Yes. See the guide _[Get API Key]({{site.cartojs_docs}}/guides/get-api-key/)_ or the [full reference API]({{site.cartojs_docs}}/reference/#authentication) for details.
If you want to learn more about authorization and authentication in the CARTO Platform, read the [fundamentals]({{site.fundamental_docs}}/authorization/) about this topic, or dig into the [Auth API]({{site.authapi_docs}}/) details.
### How do I pay for my API Keys?
All billing is managed through your CARTO account.
The release of the updated CARTO.js library does not impact your plan in any way. There are no changes in terms of costs or payments of your CARTO use.
### What are the main features of this release?
This new library allows you to create custom Location Intelligence applications using Builder capabilities.
Highlights of this release include the ability to:
1. Display data from datasets managed in Builder on a Leaflet map.
2. Manage layers programmatically.
3. Get data from CARTO to create custom UI components using Dataviews.
You can learn more about these main features reading the [final release announcement]({{site.cartojs_docs}}/support/release-announcement/).
### Where's the repository now?
The repo has been renamed and moved to https://github.com/CartoDB/carto.js.
### Does CARTO.js support Named Maps?
No.
Named Maps was a powerful and popular feature yet not easy to understand. Named maps were designed as a workaround for some of the limitations of our API keys. Named maps' purpose might be replicated by the new authorization system.
### Can I still use `cartodb.createVis` and `viz.json` URLs?
No, you cannot.
While `cartodb.createVis` and `viz.json` URLs were convenient and allowed you to prototype a map using CARTO Editor (the former version of Builder) to create a custom app, the functionality of the library has changed.
In CARTO.js v4, we are taking a more programmatic, low-level approach and identifying components that are separate from the front-end tool (CARTO Builder). This will make the API easier to use and more intuitive, giving developers greater flexibility in maintaining their core application.
### Is CartoDB.js v.3.15 still available?
Yes.
Both the [source code](https://github.com/CartoDB/carto.js/tree/v3.15.14) and the [documentation](https://carto.com/docs/carto-engine/carto-js/) are still available.

372
docs/support/03-error-messages.md Normal file
View File

@@ -0,0 +1,372 @@
## Errors
CARTO.js emits error objects when something goes wrong. Errors appear in your developer console if not caught. The error object has a code and a description to help you identify the problem and troubleshoot.
### CARTO.js API Error Codes
If you encounter an error while loading CARTO.js, the following table contains a list of known errors codes and possible solutions.
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">api-key-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">apiKey property is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">api-key-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">apiKey property must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">username-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">username property is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">username-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">username property must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">non-valid-server-url</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">serverUrl is not a valid URL.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">non-matching-server-url</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">serverUrl doesn't match the username.</p>
</td>
</tr>
</tbody>
</table>
### CARTO.js Error Codes
If you find a validation error on Chrome JavaScript Console, Firefox Web Console, or any other equivalent tools in your browser, please reference the tables below to find explanations for the validation errors. Each table gives specific error information for the different components of CARTO.js.
### Dataview
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">source-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Source property is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">column-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Column property is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">column-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Column property must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">empty-column</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Column property must be not empty.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">filter-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Filter property is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">time-series-options-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Options object to create a time series dataview is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">time-series-invalid-aggregation</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Time aggregation must be a valid value. Use carto.dataview.timeAggregation.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">time-series-invalid-offset</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Offset must an integer value between -12 and 14.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">time-series-invalid-uselocaltimezone</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">useLocalTimezone must be a boolean value.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">histogram-options-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Options object to create a histogram dataview is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">histogram-invalid-bins</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Bins must be a positive integer value.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">formula-options-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Formula dataview options are not defined.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">formula-invalid-operation</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Operation for formula dataview is not valid. Use carto.operation.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-options-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Category dataview options are not defined.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-limit-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Limit for category dataview is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-limit-number</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Limit for category dataview must be a number.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-limit-positive</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Limit for category dataview must be greater than 0.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-invalid-operation</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Operation for category dataview is not valid. Use carto.operation.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-operation-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Operation column for category dataview is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-operation-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Operation column for category dataview must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">category-operation-empty</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Operation column for category dataview must be not empty.</p>
</td>
</tr>
</tbody>
</table>
### Filter
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">invalid-bounds-object</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Bounds object is not valid. Use a <code>carto.filter.Bounds object</code>.</p>
</td>
</tr>
</tbody>
</table>
### Layer
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">non-valid-source</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">The given object is not a valid source. See <code>carto.source.Base</code>.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">bad-layer-type</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">The given object is not a layer.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">non-valid-style</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">The given object is not a valid style. See <code>carto.style.Base</code>.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">source-with-different-client</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">A layer can't have a source which belongs to a different client.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">style-with-different-client</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">A layer can't have a style which belongs to a different client.</p>
</td>
</tr>
</tbody>
</table>
### Source
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">query-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">SQL Source must have a SQL query.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">query-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">SQL Query must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">no-dataset-name</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Table name is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">dataset-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Table name must be a string.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">dataset-required</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">Table name must be a string.</p>
</td>
</tr>
</tbody>
</table>
### Style
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">required-css</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">CartoCSS is required.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">css-string</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">CartoCSS must be a string.</p>
</td>
</tr>
</tbody>
</table>
### CARTO.js Platform Error Codes for Developers
If you find an error on Chrome JavaScript Console, Firefox Web Console, or any other equivalent tools on your browsers (regarding platform (aka. backend services)), please reference the table below to find explanations for the error codes.
<table id="errors-table" class="paramsTable u-vspace--24">
<thead>
<tr>
<th class="error"><h5 class="title is-small is-regular">Error Code</h5></th>
<th class="message"><h5 class="title is-small is-regular">Message</h5></th>
<th class="description"><h5 class="title is-small is-regular">Description</h5></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tdParams error"><span class="params">over-platform-limits</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">You are over platform's limits.</p>
</td>
<td class="tdParams description">
<p class="text is-small u-tspace--4">In order to guarantee the performance of those APIs for every user of the CARTO platform and prevent abuse, we have set up some general limitations and restrictions on how they work.</p>
       <p class="text is-small u-tspace--4">Learn about fundamentals of [limits]({{site.fundamental_docs}}/limits/) in CARTO.</p>
</td>
</tr>
<tr>
<td class="tdParams error"><span class="params">generic-limit-error</span></td>
<td class="tdParams message">
<p class="text is-small u-tspace--4">The server is taking too long to respond.</p>
</td>
<td class="tdParams description"><p class="text is-small u-tspace--4">Due to poor conectivity or a temporary error with our servers, we cannot handle your request. Please try again soon.</p></td>
</tr>
</tbody>
</table>
### Checking Errors in your Browser
CARTO.js writes error messages to `window.console` if they are not caught. Please check the developer documentation for your browser in order to understand how you can check it.
If any errors occurred when loading CARTO.js, they appear as one or more lines in the console. You can check the [error codes table](#errors above to find te error in the error message. You can also find the details about the error message in the [Full Reference API]({{site.cartojs_docs}}/reference/).
Ensure that you are using a [supported browser]({{site.cartojs_docs}}/support/browsers/).

15
docs/support/04-browser-support.md Normal file
View File

@@ -0,0 +1,15 @@
## Browser Support
CARTO.js works for the last 2 versions in any modern browser and IE11.
### Desktop Browsers
| ![Chrome](https://camo.githubusercontent.com/6bb46f736c023ca3a96263d88cc30ea94a19bd3f/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f617263686976652f6368726f6d655f31322d34382f6368726f6d655f31322d34385f34387834382e706e67) | ![Firefox](https://camo.githubusercontent.com/a2f2aef3a61ac88d31266cc5745c92a0943a51fd/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f617263686976652f66697265666f785f312e352d332f66697265666f785f312e352d335f34387834382e706e67) | ![Edge](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/45.10.0/edge/edge_48x48.png) | ![Opera](https://camo.githubusercontent.com/f8b46198612edbe858c531588c179a9a564690cc/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f6f706572612f6f706572615f34387834382e706e67) | ![Safari](https://camo.githubusercontent.com/bfd047508bfa78a389415ab494cc8dcc04d94e7d/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f7361666172692f7361666172695f34387834382e706e67) | ![IE](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/45.10.0/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png) |
|:-------------:|:-------------:|:-----:|:-------------:|:-----:|:-----:|
| Chrome | Mozilla | Edge | Opera | Safari | IE 11 |
### Mobile Browsers
| ![Chrome](https://camo.githubusercontent.com/6bb46f736c023ca3a96263d88cc30ea94a19bd3f/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f617263686976652f6368726f6d655f31322d34382f6368726f6d655f31322d34385f34387834382e706e67) | ![Safari](https://camo.githubusercontent.com/bfd047508bfa78a389415ab494cc8dcc04d94e7d/68747470733a2f2f63646e6a732e636c6f7564666c6172652e636f6d2f616a61782f6c6962732f62726f777365722d6c6f676f732f33392e332e302f7361666172692f7361666172695f34387834382e706e67) | ![Samsung Internet](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/45.10.0/archive/samsung-internet_5/samsung-internet_5_48x48.png) |
|:-------------:|:-------------:|:-------------:|
| Mobile Chrome | Mobile Safari | Samsung Internet |

17
docs/support/05-release-announcement.md Normal file
View File

@@ -0,0 +1,17 @@
## v4 Release Announcement
After several months of hard work, CARTO is very proud to announce the __final release of CARTO.js v4__, which replaces our existing CartoDB.js library. We recognize that you have been anticipating an updated version for some time so before we give you the details, thank you for your patience!
The updated CARTO.js library has been __rebuilt from the ground up__. Case Studies indicated that we could change how we structured the API to make it more intuitive for developers. As a result, we created __a more low-level, programmatic approach__ which makes it easier to use and allows you to create fully customized location intelligence apps.
Some of the key features of the Beta release are:
* __A new way of displaying data__ hosted on your CARTO account, on top of Leaflet and Google Maps maps, in the form of layers.
* __A mechanism for extracting data__ from your CARTO account in predefined ways (eg: a list of categories). This is the same mechanism that Builder uses internally for its powerful widgets. It includes being able to filter this data by a bounding box.
* __A way of getting the metadata__ associated to the styles of a particular layer. For example, you will be able to get the names and colors of the categories for a layer styled using a color scheme.
We know that documentation is critical for any good JS library and used this as an opportunity to begin the redesign of how we provide documentation for all of our CARTO platform. Browse the interactive API documentation for the final release to search for specific CARTO.js methods, arguments, and sample code that can be used to build your applications.
Please use the final release and <a class="typeform-share" href="https://cartohq.typeform.com/to/mH6RRl" data-mode="popup" target="_blank">let us know what you think!</a><script>(function() { var qs,js,q,s,d=document, gi=d.getElementById, ce=d.createElement, gt=d.getElementsByTagName, id="typef_orm_share", b="https://embed.typeform.com/"; if(!gi.call(d,id)){ js=ce.call(d,"script"); js.id=id; js.src=b+"embed.js"; q=gt.call(d,"script")[0]; q.parentNode.insertBefore(js,q) } })() </script> The goal is to gather as much feedback as possible so that we can ensure CARTO.js v4 is rock-solid and super useful for all CARTO users. You can find different [support-options]({{site.cartojs_docs}}/support) if you need help.
__Happy coding!__

36
docs/support/06-contribute.md Normal file
View File

@@ -0,0 +1,36 @@
## Contribute
CARTO platform is an open-source ecosystem. You can read about the [fundamentals]({{site.fundamental_docs}}/components/) of CARTO architecture and its components.
We are more than happy to receive your contributions to the code and the documentation as well.
## Filling a ticket
If you want to open a new issue in our repository, please follow these instructions:
1. Descriptive title.
2. Write a good description, it always helps.
3. Include your browser, OS and CARTO.js version (it shows up in the browser console).
4. Specify the steps to reproduce the problem.
5. Try to add an example showing the problem (using [JSFiddle](http://jsfiddle.net), [JSBin](http://jsbin.com),...).
## Contributing code
Best part of open source, collaborate in CARTO.js code!. We like hearing from you, so if you have any bug fixed, or a new feature ready to be merged, those are the steps you should follow:
1. Fork the CARTO.js repository.
2. Create a new branch in your forked repository.
3. Commit your changes. Add new tests if it is necessary (```grunt test```), remember to follow ["How to build"](https://github.com/CartoDB/carto.js/blob/master/README.md#how-to-build) steps.
4. Open a pull request.
5. Any of the CARTO.js mantainers will take a look.
6. If everything works, it will merged and released \o/.
If you want more detailed information, this [GitHub guide](https://guides.github.com/activities/contributing-to-open-source/) is a must.
## Completing documentation
CARTO.js documentation is located in ```docs/```. That folder is the content that appears in the [Developer Center](http://carto.com/developer-center/carto-js/).
Just follow the instructions described in [contributing code](#contributing-code) and after accepting your pull request, we will make it appear online :).
## Submitting contributions
You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions).