Webinar Write-up

Andy Eschbacher | Map Scientist | CartoDB | @MrEPhysics | eschbacher@cartodb.com

Find this document here: http://bit.ly/cdb-namedmaps

You can easily make Named Maps through the CartoDB Editor anytime you create a public visualization with your private data. Just because the visualization is public doesn't mean that your data is exposed. Only the data that is sent is the data that you configure ahead of time.

Making Named Maps in CartoDB.js is similar but requires more technical skills.

In this webinar we will make a Named Map with interactivity (click events to show infowindows) and SQL querying to expose different, pre-set information about your data. With these maps you can be confident that you have control over your data.

Getting Started

You need two files and access to a command line interface (such as Terminal on Mac) to make authenticated calls to create, update, list, or delete your Named Maps configurations.

The two files are listed in this gist: index.html and webinar-config.json.

You'll also need to grab your API Key.

webinar-config.json

This file (located below) sets up the configuration (SQL and CartoCSS) of your map on the server, similar to what you would see in a viz.json or a layer you set up on the fly in createLayer

index.html

This is an HTML document (located on the current page) that sets up your map on a webpage. You have limited control over how your map looks based on how restrictive you set up your map in your config file. Most CartoDB.js methods work with named maps just as they would with maps with public datasets.

The data

I'm using a dataset of found meteorites around the world. Directly import the dataset into your CartoDB account by copying the following URL and pasting it into the Importer.

http://andye.cartodb.com/api/v2/sql?q=SELECT%20*%20FROM%20meteorites_copy&filename=meteorite&format=csv

Command-line calls

Set up your map with the following statement:

curl 'https://{your_account_name}.cartodb.com/api/v1/map/named?api_key={your_api_key}' \
  -H 'Content-Type: application/json' \
  -d @webinar-config.json

In the config file

Multiple Layers

There is an array of layers, each one an object.

"layers": [
    {
        "options": {
            "cartocss": "#meteorites{ marker-fill: #5CA2D1; marker-width: 10; marker-line-color: #FFF; marker-line-width: 0; marker-line-opacity: 1; marker-fill-opacity: 0.6; marker-comp-op: multiply; marker-type: ellipse; marker-placement: point; marker-allow-overlap: true; marker-clip: false; marker-multi-policy: largest; }",
            "cartocss_version": "2.1.1",
            "interactivity": [
                "cartodb_id",
                "mass"
            ],
            "sql": "SELECT * FROM meteorites WHERE <%= layer0 %> = 1 AND mass <= 900000"
        },
        "type": "cartodb"
    },
    ...
    ]

SQL

SELECT * FROM meteorites WHERE <%= layer1 %> = 1 AND mass > 900000 AND mass <= 20000000

CartoCSS

#meteorites{ marker-fill: #F84F40; marker-width: 10; marker-line-color: #FFF; marker-line-width: 0; marker-line-opacity: 1; marker-fill-opacity: 0.6; marker-comp-op: multiply; marker-type: ellipse; marker-placement: point; marker-allow-overlap: true; marker-clip: false; marker-multi-policy: largest; }

Placeholder parameters: layerX

There are special placeholder values layer0, layer1, etc. that allow you to toggle sublayers on or off using sublayer.toggle() (or .hide() or .show()).

By setting them as parameters in your config file and placing them into your SQL you can give client-side control over which layers are shown or hidden.

name

This is the name of the map, where the meaning of "named maps" comes from.

HTML File

Most important piece of JavaScript:

cartodb.createLayer(map, {
    user_name: '{your account name}',
    type: 'namedmap',
    named_map: {
        name: "{name of named map}",
        layers: [{
            layer_name: "small_mass",
            interactivity: "{columns selected for interactivity}"
        },
        {
            layer_name: "medium_mass",
            interactivity: "cartodb_id, mass"
        },
        {
            layer_name: "large_mass",
            interactivity: "cartodb_id, mass"
        }]
     }
}).addTo(map)

Other things to notice

The function createSelector does the toggling of the data sublayers.

Final map should look like the map at the top of this page

More information

For more information, check out the Maps API documentation, our new Named Maps tutorial, and the CartoDB.js docs.