@flourish/legend

Flourish legend component

Introduction

The legend component adds legends to a Flourish template.

There are currently three types:

• discrete (color) (displays as a series of swatches)
• continuous (color) (displays as a color band)
• continuous (size) (displays as a small and large circle)

Multiple instances of a legend may be added to a template.

Installation

npm install --save @flourish/legend

Then import into you project like this:

import { createDiscreteColorLegend } from "@flourish/legend" for discrete (color) legend

import { createContinuousColorLegend } from "@flourish/legend" for continuous (color) legend

import { createContinuousSizeLegend } from "@flourish/legend" for continuous (size) legend

Initialize the legend component

In your template.yml, add:

- property: legend
  import: "@flourish/legend/discrete-color"

for discrete (color) legend. (Use @flourish/legend/continuous-color or @flourish/legend/continuous-size for the other legend types.)

To your state, add:

state: {
  "legend": {}
}

Inside your template init code, initialize the legend component like this:

var legend = createDiscreteColorLegend(state.legend)

Add legend to your template

legend.appendTo(target_container) where target_container is a node element, for example layout.getSection("legend")

Discrete (color) legend

Add legend items to the legend and customise it

legend
  .data(array, color_function(optional)) // See explanation below
  .filtered(["Brazil"]) // Array, items that should have low opacity
  .on("click", function(d) { // Add event listener to legend items (eg. "click", "mouseover", etc.)
  	console.log(this, d, i); // (Legend item node element, {label: "Brazil", color: "#333333", index: "0"}, index)
  })
  .update(); // Update the legend

Adding data to the legend

There are two ways to add data to your legend.

1. An array of objects like this:

var legend_items = [
	{
		label: "Brazil",
		color: "#ff0000"
	},
	{
		label: "Argentina",
		color: "#000000"
	}
]
legend.data(legend_items);

1. An array of strings, with additional color function

var getColor = initializeColors(state.color).getColor; // Using Flourish custom colors module
// var getColor = function(label, i) { return color_list[label]; } // Or create your own function, referencing an object/array with colors

var legend_items = ["Brazil", "Argentina"];
legend.data(legend_items, getColor)

Continuous (color) legend

legend
  .data(domain, colorScale)
  .markerValue(500)
  .update();

domain is a 2-element array (e.g. [0, 1000]) that specifies the values at the lower and upper end of the color scale. color_scale is a color scale function (e.g. from the colors component). The markerValue method adds a black and white marker centred on its argument's value. Pass in a value of null to remove.

Continuous (size) legend

legend
  .scale(sizeScale)
  .update();

size_scale is a scale function that maps the domain to a size. For example, if the legend is representing circle size, this would typically be a D3 scaleSqrt.

It's assumed that the domain and range minima (e.g. size_scale.domain()[0]) are zero to keep things simple and because this is good practice. (It's the equivalent of starting bar charts at zero.)

If size_scale depends on the container size (which in turn depends on the size of the legend) then .update() will need to be called twice. The first call to set the height of the legend and the second call to update the legend content.

For example:

size_by_legend
  .visible(true)
  .update();

// Compute sizeScale (typically this will require calling chart-layout's update function)

size_by_legend
  .scale(sizeScale)
  .update();

Additional methods/options

legend.getContainer()

Gets the legend node element

legend.visible(true|false)

Sets the visibility of the legend.

legend.format(formatFunction)

Adds a formatter function to format the labels

legend.autoTitle(string)

Sets the automatic title for the legend. This could be a column name for example.

Multiple legend instances

A typical implementation of multiple legends might look something like:

template.yml

  - Discrete color legend
  - property: legend_discrete_color
    import: "@flourish/legend/discrete-color"

  - Continuous color legend
  - property: legend_continuous_color
    import: "@flourish/legend/continuous-color"

state.js

// Settings overrides
legend_discrete_color: {
  text_size: 0.7
},
legend_continuous_color: {
  text_size: 0.7
}

legend.js

var discrete_color_legend, continuous_color_legend;

function initLegends() {
  discrete_color_legend = createDiscreteColorLegend(state.legend_discrete_color);
  continuous_color_legend = createContinuousColorLegend(state.legend_continuous_color);

  var legend_container = layout.getSection("legend");
  discrete_color_legend.appendTo(legend_container);
  continuous_color_legend.appendTo(legend_container);
}

function updateLegends() {
  discrete_color_legend
    .data(...)
    .update();

  continuous_color_legend
    .data(...)
    .update();
}

If a legend needs to change type, add a legend for each type and use .visible() to hide/show such that one is showing at a time.