Symbols, and Backgrounds, and Data, oh my!

v0.48.0

Features

SymbolGenerators

A SymbolGenerator is a function that, given a datum and index, returns a String representing the d attribute of an SVG <path> element:

type SymbolGenerator = (datum: any, index: number) => string;

The SymbolGenerator produces a path-string assuming the <path> has a 100px by 100px space in which to render.
Some default SymbolGenerators have been included under Plottable.SymbolGenerators.d3Symbol(); for example,

Plottable.SymbolGenerators.d3Symbol("square");

returns a SymbolGenerator that draws squares. The supported symbol types are "circle", "square", "cross", "diamond", "triangle-up", and "triangle-down".

Symbols on Plot.Scatter

Plot.Scatter now uses a SymbolGenerator to determine the type of symbol rendered, rather than always rendering circles. project()-ing on to the "symbol" property will change the type of symbol drawn. For example:

scatterPlot.project("symbol", Plottable.SymbolGenerators.d3Symbol("square"));

will cause the Plot.Scatter to draw squares. As usual, the projector can be data-dependent:

var upVsDown = Plottable.SymbolGenerators.d3Symbol(function(d, i) {
  if (d.y > 0) {
    return "triangle-up";
  } else {
    return "triangle-down";
  }
});
scatterPlot.project("symbol", upVsDown);

The above code will cause different types of symbols to be shown depending on the y property of each datum:

Plot.Scatter will use a circle as the default symbol if one is not specified.

Symbols on Legend

Similarly, Legends now take a SymbolGenerator:

legend.symbolGenerator(Plottable.SymbolGenerators.d3Symbol.d3Symbol("square"));

Will cause the Legend to display squares instead of circles. The SymbolGenerator is passed the Legend entries as arguments, allowing different symbols to be displayed for different entries:

colorScale.domain(["good", "neutral", "bad"]);
var legend = new Plottable.Component.Legend(colorScale);
var nameToSymbol = {
  "good": "triangle-up",
  "neutral": "square",
  "bad": "triangle-down"
};
var generator = Plottable.SymbolGenerators.d3symbol(function(entryName, i) {
  return nameToSymbol[entryName];
});
legend.symbolGenerator(generator);

Symbols on Legend are marked with the legend-symbol CSS class if users want to style them.

background-fill on Components

Components now feature a <rect> in their background container that allows their background to be colored. For example, this CSS

.plottable .plot .background-fill {
  fill: pink;
}

Will color the background of all Plots pink:

If multiple Plots are in a Group, a more specific rule needs to be used to color only the background-fill of the Group:

.plottable .component-group > .background-container background-fill {
  fill: pink;
}

content() accessor

Components now have a content() method that retrieves the D3.Selection that they draw in, in the event that users want to use D3 to manipulate elements the Component has drawn. See below for an example use case.

Legends no longer apply CSS classes based on entry names

Legends no longer apply the name of the entry as a CSS class to the entry's <g>. To restore this behavior, add the following code:

legend.content().selectAll("." + Plottable.Component.Legend.LEGEND_ENTRY_CLASS)
                .each(function(d) {
                  d3.select(this).classed(mySanitizingFunction(d), true);
                });

This allows users to specify their preferred CSS sanitizing function (for removing spaces from the applied names, for example).

Exclude argument in getAllSelections()

plot.getAllSelections() now takes an exclude argument:

public getAllSelections(datasetKeys?: string | string[], exclude = false): D3.Selection

The optional exclude argument that defaults to false. If exclude is set to true, then all Datasets in the Plot will be queried except the ones specified by the datasetKeys argument.

getAllPlotData()

plot.getAllPlotData() returns a PlotData object containing all of the data, pixelPoints, and the selections for the specified Dataset(s):

export type PlotData = {
  data: any[];
  pixelPoints: Point[];
  selection: D3.Selection;
}

The pixelPoints property will depend on the type of Plot. For example, the returned Points will be in the center of the symbols on a Plot.Scatter, but on a Plot.Bar the Points in the center-top of the bars (or center-bottom if the bar has a negative value).

generateProjectors()

When a user passes projector information through plot.project, Plottable stores this "projector" information to render those attributes on the plot (along with defaults if those attributes have not been set). Users now have access to this information through the generateProjectors() call. This API point allow access to the "projected" information the plot uses, such as the x and y pixel values corresponding to the positions of data points, without having to inspect the rendered <svg>.

The signature is:

public generateProjectors(datasetKey: string): AttributeToAppliedProjector

An AttributeToAppliedProjector is an object maps attribute strings to a projector, which is a function that takes in a datum and an index that returns an arbitrary value:

type AttributeToAppliedProjector = { [attrToSet: string]: AppliedProjector; };
type AppliedProjector = (datum: any, index: number) => any;

An example usage:

var projectors = linePlot.generateProjectors(datasetKey);
var xProjector = projectors["x"];
var yProjector = projectors["y"];
var pixelPositions = linePlotData.map(function(datum, index) {
  return {
    x: xProjector(datum, index),
    y: yProjector(datum, index)
  };
});
// use the pixelPositions to calculate a closest point or something...

API-Breaking Changes

• Scale.Ordinal has been renamed to Scale.Category because its function deviates from the vanilla D3 ordinal scale (#1210).
• The animators on Plot.Scatter have been renamed from "circles"/"circles-reset" to "symbols"/"symbols-reset" as Plot.Scatter now renders symbols instead of circles.

Other notes

• Plottable has upgraded D3 to v3.5.5.