createVis vs. createLayer
The CartoDB.js API provides powerful tools to build dynamic web apps. Along with CartoCSS, other JS libraries, and our SQL API, the sky’s the limit. This course, CartoDB.js from the Ground Up, will show you how to build amazing apps in a small amount of time.
The first method, createVis allows for quick and easy maps with a large degree of customization. It gives two map layers in an array: layer 0 is the base map; layer 1 is the CartoDB data layer.
The second method, createLayer, allows for much more customization, including the combining of layers from separate maps, each with its own levels of customization. createLayer also allows client-side control over basemaps.
Both methods allow custom CartoCSS styling, SQL queries, and overlay options (zoom controls, a search box, a share button, etc.). Before showing these methods, we need to be introduced to these methods’ main sources of information.
viz.json, nice to meet you
Up to this point, all of the methods for displaying maps to the world have involved the first two sharing options you’ve seen in the sharing panel (see below). The first, “Get the link,” creates a shortened URL that points to a map in your account on CartoDB’s website. The second, “Embed it,” gives you an
iframe that you can drop into your custom web page. The third option, “CartoDB.js,” will be our jumping off point for this course because you’ll easily be able to see how the API’s methods line up with the data hierarchy of your map’s metadata.
A viz.json is a file that contains all the data needed to reproduce the visualization you created in CartoDB. An analogy one can make is that CartoDB.js is like a DVD player, the viz.json is like the DVD disc, and CartoDB represents all the parts needed to create a film (cameras, actors, director, producers, etc.).
Download the viz.json used in this lesson here. You can download a viz.json from any visualization you’ve created and inspect it with your favorite text editor, or view it in your browser if you have a JSON viewer. For this lesson, we will be using the viz.json for a multi-layer map similar to the one created at the end of Course 1. If you’re unfamiliar with the JSON file format, check out the official site or Wikipedia for a lot more information.
There’s a lot of metadata in this file. Browsing through all the possibilities shows you how much power you have to customize your maps in the CartoDB Editor. Review the documentation for CartoDB Editor to explore what some of these JSON entries allow you to do in your maps.
Looking at your viz.json, find the top-most level called
layers. You can see that it’s an array of two objects. The first object’s
options have type “Tiled” and a name of “CartoDB Flat Blue.” This layer,
layers, corresponds to the base layer map of our visualization. If you try changing the base map in CartoDB Editor and reload the viz.json, you will see the information in this layer change accordingly. Make note of other properties included in this
options object as they will come up again later.
The next object down,
layers, contains information about the data that was loaded into the map and visualized. The first entry,
type, tells you that this is a group of layers. Under options, you can see some of the information that’s used by the CartoDB.js API to retrieve information from the servers. In contrast to
layers, the majority of this second object in the
layers array is taken up by
layer_definition. In our case, we have two sublayers in
layers because there are two objects in the
layers array that’s under
layer_definition. In future lessons, we will retrieve these layers by calling
Looking back at our viz.json, we can see that the zeroth layer, buried under options, has a
layer_name of “us_counties” and comes from our us_counties dataset back in the Beginner’s Course. The second comes from another familiar dataset on tornados in the United States. Other important info to pick out:
- sql: tells you the SQL statement used with each data set (defaults to
select * from dataset)
- visible: means it will display (defaults to
- cartocss: tells you about the styles applied to your map
- interactivity: tells you the columns that is click/hover enabled
Check out the documentation for viz.json here.
The most basic way to display your map from CartoDB.js involves a call to
Couched between the
<script> ... </script> tags, createVis puts a map and CartoDB data layers into the DOM element you specify. In the snippet below we assume that
<div id='map'></div> placed earlier in an HTML file.
And that’s it! All you need is that snippet of code, a script block that sources CartoDB.js, and inclusion of the CartoDB.js CSS file. It’s really one of the easiest ways to create a custom map on your webpage.
createVis also accepts options that you specifiy outside of the CartoDB Editor. They take the form of a JS object, and can be passed as a third optional argument.
To see createVis out in the wild, check out an awesome example in our Map of the Week series on our blog.
A basic Leaflet map without your data can be created as follows:
The map we just created doesn’t have any CartoDB data layers yet. If you’re just adding a single layer, you can put your data on top of the basemap from above. If you want to add more, you just repeat the process. We’ll be doing much more with this later.
This is the basic snippet to put your data on top of the map you just created. Drop this in below the
Check out this Map of the Week entry to see createLayer at work.
Summing it up. And finally making something!
Now that we’re done with our crash course on the basics, let’s finally dive into making our first map with CartoDB.js.
Use this template, the URL for the viz.json linked above, and the code snippets for createVis or createLayer to make your first map using CartoDB.js. There are a couple of new things to notice about the template. Besides the normal HTML skeleton, the template includes the CartoDB.js library
<body> tags AND the map styling sheet
<head> tags. You need them both to get your maps going.
After you get it working, swap out the viz.json we provided with some of the viz.jsons from your own visualizations. Try putting in the createVis examples introduced before. Check out stellar examples in the Map Gallery, look at some of the examples in the official CartoDB.js repository, and hack away! If you prefer JS Fiddle, run the demo here.
By the way, CartoDB.js is open source. Fork it and contribute.