[Draft] Infowindow API Proposal

Intro

Current Infowindow API is okay, but users are asking for more. Let's see can we can improve that! 😄

What we have today (06/2015)

Adding infowindows dynamically

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. The following options could be specified: templateType, triggerEvent, templateName, extraFields, cursorInteraction (but they are not documented in the docs).

Here's an example (using cartodb.createLayer):

var map = L.map('map', { ... });

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']);
  });

And here's another example (using cartodb.createVis):

cartodb.createVis('map', 'https://wadus.cartodb.com/api/v2/viz/48b32c96-ffce-11e4-96bd-0e4fddd5de28/viz.json', {...})
  .done(function(vis, layers) {
    var sublayer = layers[1].getSubLayer(0);

    // you can get the native map to work with it
    var map = vis.getNativeMap();

    // It doesn't work if we don't set this
    map.viz = vis;

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

    // Since we have the `vis` here, it would probably be easier to do something like:
    // vis.addInfowindow(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.

Hacking a custom infowindow

Someone could hack a custom infowindow by listening and taking advantage of the featureClick event on a sublayer.

Here's an example:

  sublayer.setInteraction(true);
  sublayer.setInteractivity('place');

  sublayer.on('featureClick', function(e, latlng, pos, data, layerNumber) {
    cartodb.log.log(e, latlng, pos, data, layerNumber);
    $("#myInfowindow").css({'display':'block','left':pos.x-75,'bottom':($(window).height()-pos.y+20), 'cursor': 'pointer'});
    $("#myInfowindow").find('p').text(data.place);
  });

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).

Infowindow API 2.0

New features:

• Open an infowindow in a position / feature.
• Close an infowindow.
• Listen to events on infowindows (DOMReady).
• ...

TODO: Continue with the specification of the API.

Existing JS APIs for infowindows/popups:

• GMaps InfoWindow API. Features:
• Customize the infowindow via options.
• Getting/setting the content of an infowindow (also an option).
• Getting/setting the position (latlng) of the infowindow (also an option).
• Open an infowindow in a map (in the given position or in the position of an associated marker).
• Listen to events that are triggered when attributes change, DOM inside of the infowindow is ready, etc.
• Leaflet Popup API. Features:
• Customize the infowindow via options.
• Add a popup to a map.
• Open a popup on a map.
• Getting/setting the content of the popup.
• Getting/setting the position (latlng) of the popup.