Skip to content

Commit 91ccfd6

Browse files
author
rubenmoya
committed
Merge branch 'master' into 2139-add-metric
2 parents 2e8e879 + a87594d commit 91ccfd6

28 files changed

+656
-41
lines changed

‎docs/guides/01-overview.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
## Overview
2+
3+
CARTO.js lets you create custom location intelligence applications that leverage the power of the CARTO Platform.
4+
5+
### Audience
6+
7+
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.
8+
9+
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/).
10+
11+
### Hello, World
12+
13+
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.
14+
15+
```html
16+
<!DOCTYPE html>
17+
<html>
18+
<head>
19+
<title>Single layer | CARTO</title>
20+
<meta name="viewport" content="initial-scale=1.0">
21+
<meta charset="utf-8">
22+
<!-- Include Leaflet -->
23+
<script src="https://unpkg.com/leaflet@1.3.1/dist/leaflet.js"></script>
24+
<link href="https://unpkg.com/leaflet@1.3.1/dist/leaflet.css" rel="stylesheet">
25+
<!-- Include CARTO.js -->
26+
<script src="https://libs.cartocdn.com/carto.js/v4.0.8/carto.min.js"></script>
27+
<link href="https://fonts.googleapis.com/css?family=Montserrat:600" rel="stylesheet">
28+
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet">
29+
<link href="https://carto.com/developers/carto-js/examples/maps/public/style.css" rel="stylesheet">
30+
</head>
31+
<body>
32+
<div id="map">
33+
</div>
34+
<!-- Description -->
35+
<aside class="toolbox">
36+
<div class="box">
37+
<header>
38+
<h1>Add a layer</h1>
39+
<button class="github-logo js-source-link"></button>
40+
</header>
41+
<section>
42+
<p class="description open-sans">Add one CARTO layer to your map.</p>
43+
</section>
44+
<footer class="js-footer"></footer>
45+
</div>
46+
</aside>
47+
48+
<script>
49+
const map = L.map('map').setView([30, 0], 3);
50+
map.scrollWheelZoom.disable();
51+
52+
L.tileLayer('https://{s}.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png', {
53+
maxZoom: 18
54+
}).addTo(map);
55+
56+
const client = new carto.Client({
57+
apiKey: 'default_public',
58+
username: 'cartojs-test'
59+
});
60+
61+
const source = new carto.source.Dataset(`
62+
ne_10m_populated_places_simple
63+
`);
64+
const style = new carto.style.CartoCSS(`
65+
#layer {
66+
marker-width: 7;
67+
marker-fill: #EE4D5A;
68+
marker-line-color: #FFFFFF;
69+
}
70+
`);
71+
const layer = new carto.layer.Layer(source, style);
72+
73+
client.addLayer(layer);
74+
client.getLeafletLayer().addTo(map);
75+
</script>
76+
</body>
77+
</html>
78+
```
79+
80+
[View example]({{site.cartojs_docs}}/examples/#example-add-a-layer).
81+
82+
Even in this simple example, there are a few things to note:
83+
84+
- We declare the application as HTML5 using the `<!DOCTYPE html>` declaration.
85+
- We load the CARTO.js library using a `script` tag.
86+
- We create a `div` element named "map" to hold the map.
87+
- We define the JavaScript that creates a map in the `div`.
88+
89+
These steps are explained below.
90+
91+
### Declaring your application as HTML5
92+
93+
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:
94+
95+
```html
96+
<!DOCTYPE html>
97+
```
98+
99+
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.
100+
101+
We add styles to the map through the file `style.css`, declaring:
102+
103+
```css
104+
body {
105+
margin: 0;
106+
padding: 0;
107+
}
108+
109+
#map {
110+
position: absolute;
111+
height: 100%;
112+
width: 100%;
113+
z-index: 0;
114+
}
115+
```
116+
117+
This CSS declaration indicates that the map container <div> (with id map) should take up 100% of the height of the HTML body.
118+
119+
### Loading the CARTO.js library
120+
121+
To load the Maps JavaScript API, use a script tag like the one in the following example:
122+
123+
```html
124+
<script src="https://libs.cartocdn.com/carto.js/v4.0.8/carto.min.js"></script>
125+
```
126+
127+
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.
128+
129+
#### HTTPS or HTTP
130+
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.
131+
132+
We recommend loading the CARTO.js library over HTTPS using the <script> tag provided above.
133+
134+
### Map DOM Elements
135+
136+
```html
137+
<div id="map"></div>
138+
```
139+
140+
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).
141+
142+
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.
143+
144+
### Map options
145+
146+
In this example, we are using Leaflet to render the map:
147+
148+
```javascript
149+
const map = L.map('map').setView([30, 0], 3);
150+
```
151+
152+
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).
153+
154+
#### Zoom Levels
155+
156+
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**.
157+
158+
### Troubleshooting
159+
160+
If your code isn't working:
161+
162+
- Look for typos. Remember that JavaScript is a case-sensitive language.
163+
- Check the basics. Some of the most common problems occur with the initial map creation. Such as:
164+
- Confirm that you've specified the zoom and center properties in your map options.
165+
- Ensure that you have declared a div element in which the map will appear on the screen.
166+
- Ensure that the div element for the map has a height.
167+
- Refer to our [examples]({{site.cartojs_docs}}/examples/) for a reference implementation.
168+
- Use a JavaScript debugger to help identify problems. Chrome Developer Tools is a good one.
169+
- 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/).

‎docs/guides/02-get-api-key.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
## Get API Key
2+
3+
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.
4+
5+
### Quick guide to getting a key
6+
7+
#### Step 1: Get an API Key from your CARTO account
8+
9+
Start creating your API key, [registering a project](https://carto.com/login) in the CARTO Platform.
10+
11+
Notes:
12+
13+
- **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.
14+
- **Enterprise customers**: For production-ready apps, you must use a restricted API key.
15+
16+
For more information, see the [fundamentals about authorization]({{site.fundamental_docs}}/authorization/).
17+
18+
#### Step 2: Add the API key and username to your application
19+
20+
After loading the CARTO.js library, substitute YOUR_API_KEY in the code below with the API key you got from the previous step.
21+
22+
```javascript
23+
var client = new carto.Client({
24+
apiKey: '{YOUR_API_KEY}',
25+
username: '{username}'
26+
});
27+
```
28+
29+
You can get your username following these steps:
30+
31+
- Login into to your CARTO account.
32+
- Go to your account from the left menu.
33+
- Copy the username under the plan information.
34+
35+
#### More about API keys
36+
37+
The API key allows you to control your applications in the CARTO Platform.
38+
39+
If you are a Trial Plan customer, with an API key you have access to all the Engine features.
40+
41+
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.
42+
43+
#### Detailed guide for users of the CARTO.js library
44+
45+
Follow these steps to get an API key:
46+
47+
- Go to your CARTO account.
48+
- Go to your API Keys dashboard.
49+
- Click "NEW API KEY" to create a new one.
50+
- If you want to manage projects, you can regenerate or delete them.
51+
- On the API key page, configure it giving a name and the APIs and Datasets you want to use.
52+
53+
For more information on using the CARTO Platform, see our [fundamentals]({{site.fundamental_docs}}/).
54+
55+
56+
#### Troubleshooting authorization issues
57+
58+
If your API key is malformed or you supply an invalid username, the CARTO.js library returns an HTTP 403 (Forbidden) error.
59+
60+
CARTO Enterprise customers have access to enterprise-level support through CARTO’s support representatives available at enterprise-support@carto.com.

‎docs/guides/01-quickstart.md renamed to ‎docs/guides/03-quickstart.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
## Quickstart Guide
22

3-
Welcome to the CARTO.js documentation. CARTO.js is a JavaScript library that enables you to create custom location intelligence applications that leverage the power of the **[CARTO Engine](https://carto.com/pricing/engine/)** ecosystem.
3+
CARTO.js lets you create custom location intelligence applications that leverage the power of the **[CARTO Engine](https://carto.com/pricing/engine/)** ecosystem.
4+
5+
This document details CARTO.js v4. To update your v3 apps, please consult the [Upgrade Considerations]({{site.cartojs_docs}}/guides/upgrade-considerations/).
46

57
### About this Guide
68

@@ -12,6 +14,10 @@ This guide describes how to create a Leaflet map and display data from CARTO ove
1214

1315
**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/).
1416

17+
### Audience
18+
19+
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.
20+
1521
### Requesting an API Key
1622

1723
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.
@@ -393,4 +399,10 @@ client.addDataview(countriesDataview);
393399
</a>
394400
</div>
395401

402+
### Troubleshooting and support
403+
404+
For more information on using the CARTO.js library, take a look at the [support page]({{site.cartojs_docs}}/support/).
405+
406+
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/).
407+
396408
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.

‎docs/guides/02-upgrade-considerations.md renamed to ‎docs/guides/04-upgrade-considerations.md

File renamed without changes.

‎docs/guides/03-glossary.md renamed to ‎docs/guides/05-glossary.md

File renamed without changes.

‎docs/support/01-support-options.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Feeling stuck? There are many ways to find help.
44

55
* Ask a question on [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/carto) using the `CARTO` tag.
66
* [Report an issue](https://github.com/CartoDB/carto.js/issues) in Github.
7-
* Engine Plan customers have additional access to enterprise-level support through CARTO's support representatives.
7+
* Enterprise Plan customers have additional access to enterprise-level support through CARTO's support representatives.
88

99
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>.
1010

@@ -29,9 +29,9 @@ When posting a new question, please consider the following:
2929
* Be informative in your post. Details, code snippets, logs, screenshots, etc. help others to understand your problem.
3030
* Use code that demonstrates the problem. It is very hard to debug errors without sample code to reproduce the problem.
3131

32-
### Engine Plan Customers
32+
### Enterprise Plan Customers
3333

34-
Engine 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)
34+
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)
3535

3636
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.
3737

‎docs/support/02-faq.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ CARTO.js 4.0 introduces new concepts that in some cases, change the behavior of
44

55
### Do I need an API Key?
66

7-
Yes. See the [full reference API]({{site.cartojs_docs}}/reference/#authentication) for details.
7+
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.
88

9-
If you want to learn more about authorization and authentication, read the [fundamentals]({{site.fundamental_docs}}/authorization/) about this topic, or dig into the [Auth API]({{site.authapi_docs}}/) details.
9+
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.
1010

1111
### How do I pay for my API Keys?
1212

‎examples/examples.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,14 @@
176176
"leaflet": "public/misc/error-handling-leaflet.html",
177177
"gmaps": "public/misc/error-handling-gmaps.html"
178178
}
179+
},
180+
{
181+
"title": "Hexagon aggregation",
182+
"desc": "Aggregate point data into hexagon grid",
183+
"file": {
184+
"leaflet": "public/misc/hexagon-aggregation-leaflet.html",
185+
"gmaps": "public/misc/hexagon-aggregation-gmaps.html"
186+
}
179187
}
180188
]
181189
}

‎examples/public/dataviews/time-series.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ <h2 class="h2">Column</h2>
2020
<h2 class="h2">Aggregation</h2>
2121
<select id="aggregation" class="select">
2222
<option value="auto">Auto</option>
23+
<option value="millennium">Millennium</option>
24+
<option value="century">Century</option>
25+
<option value="decade">Decade</option>
2326
<option value="year">Year</option>
2427
<option value="quarter">Quarter</option>
2528
<option value="month">Month</option>

0 commit comments

Comments
 (0)