cartodb/lib/assets/javascripts/cdb/UPGRADE.md

Upgrading from v1 (cartodb-gmapsv3 | leaflet) or v2 (v2.0.28) to latest CartoDB.js v3

If your application is running an old CartoDB javascript library, you should take into account that the creation layer method and layer functions won't work as expected.

• Creation
• Methods
  • setMap
  • setQuery
  • setStyle
  • setLayerOrder
  • isAdded
  • setBounds

---

Creation

You should follow the instructions we have in our documentation. You will find layer available options and code examples there.

---

Methods

Following methods are not supported or have changed:

• setMap: use addTo instead.

  • v1:

  var layer = new L.CartoDBLayer({
    map: map,
    user_name:'cartodb_user',
    table_name: 'table_name',
    query: "SELECT * FROM {{table_name}}",
    tile_style: "#{{table_name}} {marker-fill:red}"
  })
  map.addLayer(layer);
  

  • v2:

  cartodb.createLayer(map, layerUrl, options, function(layer) {
    // For Leaflet
    map.addLayer(layer);
  
    // For GMaps
    map.overlayMapTypes.setAt(0, layer);
  });
  

  • v3:

  cartodb.createLayer(map, layerUrl, options)
    .addTo(map)
    .on('done', function(layer) { ... });
  

• setQuery: use setSQL instead.

  • v1:

  layer.setQuery("SELECT * FROM {{table_name}} WHERE cartodb_id = 3");
  

  • v2:

  layer.setQuery("SELECT * FROM table_name WHERE cartodb_id = 10");
  

  • v3:

  layer.setSQL("SELECT * FROM table_name WHERE cartodb_id = 9");
  

• setStyle: use setCartoCSS instead.

  • v1:

  layer.setStyle("#{{table_name}} { marker-fill:purple }");
  

  • v2:

  layer.setCartoCSS("#layer { marker-fill:pink }");
  

  • v3:

  layer.setCartoCSS("#layer { marker-fill:yellow }");
  

• setLayerOrder: no alternative, check proper map library methods.

  • v1:

  layer.setLayerOrder(2); // Only available for GMaps
  

  • v2: check v3

  • v3: Leaflet(1), Leaflet(2) or GMaps.

  // For Leaflet
  layer.bringToFront();
  layer.bringToBack();
  layer.setZIndex();
  
  // For GMaps
  map.overlayMapTypes.setAt(0, layer);
  

• isAdded: check it with proper map library functions (Leaflet or GMaps).

  • v1:

  layer.isAdded(); // Returned true or false
  

  • v2: check v3

  • v3: Leaflet or GMaps.

  // For Leaflet
  map.haslayer(layer);
  
  // For GMaps
  var added = false;
  map.overlayMapTypes.forEach(function(lyr){
    if (lyr === layer) added = true;
  });
  

• setBounds: you can get the needed info using CartoDB SQL (example).

  • v1:

  layer.setBounds("SELECT * FROM {{table_name}} WHERE cartodb_id < 100");
  

  • v2: check v3

  • v3:

  var sql = new cartodb.SQL({ user: 'cartodb_user' });
  sql.getBounds('select * from table').done(function(bounds) {
    console.log(bounds);
  });