Name: CartoTemplate
Owner: datamade
Description: A starter template for building interactive Carto maps.
Created: 2016-10-05 21:47:56.0
Updated: 2018-03-09 04:13:47.0
Pushed: 2017-03-24 16:18:14.0
Size: 265
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A starter template for building interactive Carto maps.
This template offers an entry point into the seemingly complicated world of Carto and data visualization.
This template depends on other JS libraries and resources:
We recommend that, at minimum, you download the source files for Carto.JS and leaflet-google, since you may wish to hack leaflet-google to customize the map style (see below). Hosting your files locally - rather than pointing to a CDN - also ensures simplicity and tearless nights, when Carto or Leaflet quietly releases an updated library. Alternatively, you can simply fork or clone this repo (learn more below) and use the included versions of Carto and Leaflet libraries.
Find data. Make a table.
To populate your interactive map, you need a Carto dataset. You can create a free account and learn about setting up your data on the official Carto website. If you need resources or ideas, consider using the Chicago Data Portal.
Look inside
The Carto Template employs two JavaScript principles: (1) constructor functionality and (2) prototype patterning, in which an object acquires new properties (functions) through Object.prototype.
Carto Template uses a constructor function - one of several JS strategies for making reusable objects (similar to a “class,” for our OOP readers). We call our constructor function CartoObj. CartoObj stores all attributes essential for building a map, such as your Carto table name, username, and fields.
CartoObj can do a lot! It creates maps, adds layers, brokers precise location searches, and so forth. You can find its functions inside CartoObj.prototype, an object literal that overrides the original prototype property of CartoObj.
Let's look at some code. What follows describes the project-specific attributes of the constructor function. You need to adjust some of these, but you may also add more, depending on the needs of your project.
oTableName
The name of of your Carto table. Again, you can visit the Carto website to learn about opening an account and creating a dataset.
oUserName
The username associated with your Carto account.
ivName
The unique id of the div where the map renders. You can find this in index.html. Our template uses mapCanvas, but you can call it anything you like.
ds
An important one! This variable includes the column names from Carto that you want to display somewhere on the site (e.g., in a modal, a text box that displays on hover, etc). A single typo in the fields variable will cause your map to crash…silently.
entroid
The latitude and longitude coordinates of the map's focal point. Here's one site to help you find the right digits.
ultZoom
The default distance away from the mapCentroid. Increase the zoom to get closer; decrease the zoom to move further out.
Step-by-step instructions
Make a copy of the Carto Template. You can fork this repo or clone it onto your local machine.
clone git@github.com:datamade/CartoTemplate.git
Open js/cartoObj.js. Modify the attributes of CartoObj. You can change the values in the constructor function itself:
tion CartoObj() {
.cartoTableName = 'exciting_new_dataset',
Or you can change these attributes, after instantiating a new instance of CartoObj:
myCarto = new CartoObj;
rto.cartoTableName = 'exciting_new_dataset';
Regardless of the strategy, you need to customize the following: cartoTableName, cartoUserName, fields, and mapCentroid.
Add an info window with a generic message or information about the location markers. This info box appears when a user hovers over a marker.
Create your unique html in the makeInfoText function. Add your custom HTML by parsing the data object, for example:
park = "<p><i class='fa fa-map-marker' aria-hidden='true'></i> " + data.park_name + "</p>"
Then, adjust its position on the map by passing in parameters to addInfoBox. You might try: “bottomleft,” “topright,” or “topleft.“”
Define a sublayer or two. You need to define a SQL query (select everything?), the ID name that styles your location markers, e.g. '#carto-result-style' (see below for customizing your location markers), and the interactivity (required to enable hover and click functionality).
layer1 = {
l: 'select * from ' + myCarto.cartoTableName,
rtocss: $('#carto-result-style').html().trim(),
teractivity: myCarto.fields,
You can create as many layers as you like - indeed, experiment with writing different SQL query, or create a new instance of CartoObj to query multiple datasets.
Finally, add your layer(s) to the map. Pass in each layer as a parameter to createCartoLayer.
rto.createCartoLayer(layer1, layer2, layer3).addTo(myCarto.map)
You can customize the map itself and the data points that populate it.
Open leaflet-google.js, and find the “options” object. Add a property called “mapOptions,” and give it any number of elements, for example:
ptions: {
backgroundColor: '#dddddd'
}
Locate _initMapObject, and add a styles property within the “map” variable, as such:
es: this.options.mapOptions.styles
In the body of the HTML file, add a style tag with a unique id. Inside this, put a CSS selector with styles that customize the appearance of the location markers, for example:
le id="carto-result-style">
#carto-result {
marker-fill-opacity: 0.9;
marker-line-color: #FFF;
marker-line-width: 1;
marker-line-opacity: 1;
marker-placement: point;
marker-type: ellipse;
marker-width: 8;
marker-fill: #3E7BB6;
marker-allow-overlap: true;
}
yle>
If something is not behaving intuitively, it is a bug, and should be reported. Report it here: https://github.com/datamade/CartoLib/issues