[Draft] Infowindow API Proposal

Intro

Current Infowindow API has been very good so far, but users are asking for more. Let's see can we can improve that! 😄

What we have today

Adding an infowindow to a sublayer

cdb.vis.Vis.addInfowindow(map, layer, fields [, options]) allows us to setup an infowindow for a layer. We need to pass a native map, the sublayer and an array of strings with the names of the fields that will be displayed. Some options (template, etc.) can also be specified, but they are not documented in the docs.

Here's an example:

cartodb.createLayer(map, {
  ...
  })
  .addTo(map)
  .done(function(layer) {
    var sublayer = layer.getSubLayer(0);
    sublayer.setInteraction(true); // It looks like this is not necessary

    cdb.vis.Vis.addInfowindow(map, sublayer, ['cartodb_id','name']);
  });

More info here.

Customizing infowindows

Infowindows can be customized via sublayer.infowindow. This is a Backbone.Model with the following attributes: template, sanitizeTemplate, width, maxHeight. This model exposes some more attributes like: fields, etc, but they are not documented.

Here's an example:

  ...
  sublayer.infowindow.set({
    template: $('#infowindow_template').html(),
    width: 218,
    maxHeight: 100
  });
  ...

More info here.

What users are asking for

• Create infowindows form scratch (without the need of a viz.json).
• Open/close an infowindow from javascript and listen to events to know when this happens (example).
• DOMready events to do things after infowindow it's rendered.
• Change data provider for infowindows. For example: many users want to show data from a custom sql based on cartodb_id and other stuff (example).
• Show custom content, like graphs generated using Google Charts (example).
• Extend template formatting options (to format numbers and so on).
• Manage layer order interaction properly.
• Customize infowindow size from CartoDB. Currently this can be done using cartodb.js using a hack (so an API endpoint should be provided for that (example).

Similar JS APIs for infowindows/popups:

• GMaps InfoWindow API.
• Leaflet Popup API.