Add a legendFormatter option

[danvk]

This is intended to be a catch-all for legend formatting needs. This comes up often in Stack Overflow questions which can't be easily answered with valueFormatter. Nowadays I wave my hands and say "write your own legend, either as a plugin or using highlightCallback and unhighlightCallback." This is a simpler option.

The legendFormatter is repeatedly called with a data object describing the selection or lack of selection. It contains all the information you need to generate a standard legend (e.g. formatted values), but there's nothing preventing you from doing something crazier on your own.

For example, here's what a simple legendFormatter might look like:

function legendFormatter(data) {
  if (data.x == null) return '';  // no selection
  return data.xHTML + data.series.map(v => v.labelHTML + ': ' + v.yHTML).join(' ');
}

Here's what the data object looks like when nothing is selected:

{
  "dygraph": "(dygraph)",
  "series": [
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,128,0);\"></div>",
      "label": "Y1",
      "labelHTML": "Y1",
      "visible": true,
      "color": "rgb(0,128,0)"
    },
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,0,128);\"></div>",
      "label": "Y2",
      "labelHTML": "Y2",
      "visible": true,
      "color": "rgb(0,0,128)"
    }
  ]
}

The dashHTML properties help you render lines which match each series' line on the chart. When strokePattern is set, they become dotted or dashed lines as needed.

Each value has a corresponding HTML variant, which is properly formatted and escaped according to all the relevant options which have been set for the chart.

Here's what it looks like when a row is selected:

{
  "dygraph": "(dygraph)",
  "x": 93,
  "xHTML": 93,
  "series": [
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,128,0);\"></div>",
      "label": "Y1",
      "labelHTML": "Y1",
      "visible": true,
      "color": "rgb(0,128,0)",
      "y": 93,
      "yHTML": "93"
    },
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,0,128);\"></div>",
      "label": "Y2",
      "labelHTML": "Y2",
      "visible": true,
      "color": "rgb(0,0,128)",
      "y": 26.04,
      "yHTML": "26.04"
    }
  ]
}

Here's what it looks like when a single series is selected (e.g. with highlightSeriesOpts):

{
  "dygraph": "(dygraph)",
  "x": 94,
  "xHTML": 94,
  "series": [
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,128,0);\"></div>",
      "label": "Y1",
      "labelHTML": "Y1",
      "visible": true,
      "color": "rgb(0,128,0)",
      "y": 94,
      "yHTML": "94",
      "isHighlighted": true
    },
    {
      "dashHTML": "<div style=\"display: inline-block; position: relative; bottom: .5ex; padding-left: 1em; height: 1px; border-bottom: 2px solid rgb(0,0,128);\"></div>",
      "label": "Y2",
      "labelHTML": "Y2",
      "visible": true,
      "color": "rgb(0,0,128)",
      "y": 22.56,
      "yHTML": "22.56"
    }
  ]
}

(Note the isHighlighted property set on Y1.)

Fixes #407

[danvk]

cc @kberg @klausw @paulfelix @hulkholden thoughts on the legendFormatter API described above?

[danvk]

Warnock applies. I'll interpret everyone's silence as approval. Merging.

[davidporter]

When I g.setVisibility(0, false) for a parameter, my legend no longer follows. I can't figure out why!? I tried updateOptions({legend: 'follow'}), but no luck. What can I do to fix?

[davidporter]

Can I use legend-formatter to flip the legend when it gets close to the end? Can I customize the leftLegend value? My legend goes off of the screen when I get to the end.