IMPORTANT

This library is deprecated. We have created a new library called CartoDB.js that includes all the funcionality of this library plus many more things. This library isn't going to be updated anymore. If you have any questions don't hesitate to send us an email to [email protected].

What is the CartoDB library for Leaflet?

This library allows you to use your own CartoDB tables with Laeflet.

Using the library

Using the library is really easy. It accepts the following parameters to manage the behavior of your CartoDB layers:

Parameter name	Description	Type	Callback variables	Required
map	The Leaflet Map object.	Object		Yes
username	Your CartoDB user name.	String		Yes
table_name	Your CartoDB table name.	String		Yes
query	An SQL query.	String		Yes
opacity	If you want to change the opacity of the CartoDB layer.	Number		No
interactivity	If you want to add interactivity to the layer without making requests.	String (columns separated by commas)		No
featureOver	A callback when hovers over a feature	Function	event: Mouse event object latlng: The LatLng leaflet object where was clicked pos: Object with x and y position in the DOM map element data: The CartoDB data of the clicked feature with the `interactivity` param.	No (But only will work with `interactivity` specified)
featureOut	A callback when hovers off a feature	Function		No (But only will work with `interactivity` specified)
featureClick	A callback when clicks on a feature	Function	event: Mouse event object latlng: The LatLng leaflet object where was clicked pos: Object with x and y position in the DOM map element data: The CartoDB data of the clicked feature with the `interactivity` param.	No (But only will work with `interactivity` specified)
attribution	Set the layer attribution.	String		No
tile_style	If you want to add other style to the layer.	String		No
auto_bound	If you want to zoom in to the area where the layer is positioned.	Boolean		No
debug	If you want to debug the library, set to true.	Boolean		No
tiler_protocol	Tiler protocol (opcional - default = 'http').	No
tiler_domain	Tiler domain (opcional - default = 'cartodb.com').		No
tiler_port	Tiler port as a string (opcional - default = '80').		No
sql_protocol	SQL API protocol (optional - default = 'http').	String		No
sql_domain	SQL API domain (optional - default = 'cartodb.com').	String		No
sql_port	SQL API port as a string (optional - default = '80').	String		No

Usage notes

If you want to get a feature clicked || hover data (via the interactivity parameter), the columns must be in a string separated by commas. If you don't want to write the name of the table several times, you can use {{table_name}} in the query or tile_style parameters. We strongly recommend the use of the files available in this repository. These are tested, and if you decide use updated ones, the library may not work.

Creating an example

There are several usages of this library in examples folder.

First of all add the necessary script and css files:

<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.4.4/leaflet.css" />
<!--[if IE]><link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.4.4/leaflet.ie.css" /><![endif]-->
<link  href="css/cartodb-leaflet.css" rel="stylesheet" type="text/css">
<script src="http://cdn.leafletjs.com/leaflet-0.4.4/leaflet.js"></script>
<script type="text/javascript" src="js/wax.leaf.min.js"></script>
<script type="text/javascript" src="dist/cartodb-leaflet-min.js"></script>
<script type="text/javascript" src="dist/cartodb-popup.js"></script>

• We strongly recommend using the library files we have in this repository, they are fully tested.

When the document is loaded, start creating the map:

var map = new L.Map('map');
var cloudmadeUrl = 'http://{s}.tile.cloudmade.com/BC9A493B41014CAABB98F0471D759707/997/256/{z}/{x}/{y}.png',
	cloudmadeAttrib = 'Map data © 2011 OpenStreetMap contributors, Imagery © 2011 CloudMade',
	cloudmade = new L.TileLayer(cloudmadeUrl, {maxZoom: 18, attribution: cloudmadeAttrib});
map.addLayer(cloudmade);

After that, create the CartoDB layer:

var cartodb_leaflet = new L.CartoDBLayer({
  map: map,
  user_name:'examples',
  table_name: 'earthquakes',
  query: "SELECT * FROM {{table_name}}",
  tile_style: "#{{table_name}}{marker-fill:red}",
  interactivity: "cartodb_id, magnitude",
  featureClick: function(ev, latlng, pos, data) {alert(data)},
  featureOver: function(){},
  featureOut: function(){},
  attribution: "CartoDB",
  auto_bound: true
});

And finally add it to the map:

map.addLayer(cartodb_leaflet);

Functions

New funcionalities are coming, in the meantime you can use:

• removeLayer: Removes the cartodb layer from the map. Example: map.removeLayer(cartodb_leaflet);
• hide: Hide the cartodb layer from the map. Example: cartodb_leaflet.hide();
• show: Show the cartodb layer in the map again. Example: cartodb_leaflet.show();
• setInteraction: Set the interaction of your layer to true or false. Example: cartodb_leaflet.setInteraction(false);
• setAttribution: Set the layer attribution. Example: cartodb_leaflet.setAttribution("CartoDB");
• setOpacity: Change the opacity of the CartoDB layer. Example: cartodb_leaflet.setOpacity(0.3);
• setQuery: Change the query parameter for the layer. Example: cartodb_leaflet.setQuery("SELECT * FROM {{table_name}} WHERE cartodb_id > 10");
• setStyle: Change the style of the layer tiles. Example: cartodb_leaflet.setStyle("#{{table_name}}{marker-fill:blue}");
• isVisible: Get the visibility of the layer. Example: cartodb_leaflet.isVisible();
• isAdded: Returns true if the layer is already added to the map. Example: cartodb_leaflet.isAdded();
• setInteractivity: Change the columns you want to get data (it needs to reload the tiles). Example: cartodb_leaflet.setInteractivity("cartodb_id, the_geom, magnitude");
• setBounds: Set bounds in the map using a new query or the default one. Example: cartodb_leaflet.setBounds(); || cartodb_leaflet.setBounds("SELECT * FROM {{table_name}} WHERE cartodb_id < 100");
• setOptions: Change any parameter at the same time refreshing the tiles once. Example: cartodb_leaflet.setOptions({query: "SELECT * FROM {{table_name}} WHERE cartodb_id<100", interactivity: "cartodb_id,the_geom,magnitude"});
• setLayerOrder: Not available yet -> Waiting for this ticket fixed: https://github.com/CloudMade/Leaflet/issues/505