@flourish/facets

Flourish facets module

A Flourish module for creating grid layouts, typically used for “small multiples” visualizations.

How to install

npm install -s @flourish/facets

Add a facets object to your template state, e.g.:

export var state = {
	facets: {},
	...
}

Next import the settings into template.yml settings, e.g.:

- Grid of chart
- property: facets
  import: "@flourish/facets"

How to use

Initialize the layout (only once) outside any function with a facet settings object:

import initFacets from "@flourish/facets";
var facets = initLayout(state.facets);

Next, in the draw function, append the facets grids to an SVG group element in your visualization, e.g.:

facets.appendTo(my_svg_g_element);

API reference

The facets object has a number of methods:

Getter/setters

facets.height(number)

When called with number, sets the overall height of the facet grid in pixels (clearing any value passed in by facets.facetHeight or facets.facetAspect) and returns the instance. When called without an argument returns the computed height of the grid.

Setters

facets.appendTo(container)

Appends the SVG group element containing the facet groups to the specified container (which should be an SVG group element), and returns the instance.

facets.data(data, accessor)

Sets the facets in the grid and returns the instance. data should be an array of strings containing the names of the facets. Alternatively, data can be a richer array, in which case also provide an accessor function that takes each entry as an argument and returns the name.

facets.width(number)

Sets the overall width of the facet grid, and returns the instance.

facets.facetHeight(number)

When called with number, sets the height of each facet in the grid in pixels (clearing any value passed in by facets.height or facets.facetAspect) and returns the instance. The specified height excludes the facet header, if present.

facetAspect(number, padding)

When called with number, sets the aspect ratio of each facet in the grid (clearing any value passed in by facets.height or facets.facetAspect) and returns the instance. The aspect applies to the main part of the facet (i.e. excluding the header, if present) and should be in the format where 1 is square. The optional padding object, if provided, can contain any combination of top, right, left and right properties. These will be taken account of when setting the aspect ratio - useful for example to set a square plot with uneven margins around the edge for the axes.

facets.duration(number)

Sets the duration, in milliseconds, of the animations in the update function, and returns the instance.

facets.autoTitleAlign(callback)

Sets how the titles should be aligned when the relevant setting is set to “Auto”, and returns the instance. callback is a function that should return "left", "center" or "right".

facets.titleColor(function)

By default facet titles are all the same and can be specified in the settings. This methods allows you to change that by passing in a function that takes the facet name as an argument and returns a color. A typical use case is to pass in the getColor function from an instance of @flourish/colors.

facets.axisSpaceTop(number), facets.axisSpaceBottom(number), facets.axisSpaceLeft(number), facets.axisSpaceRight(number)

Creates optional blank space around the grid, typically used to house axes that area shared across whole rows/columns of facets, and returns the instance. number is the size in pixels. The margins default to zero.

facets.debug(debug)

If debug is truthy, adds fills to the facets to make it possible to see the grid, and returns the instance.

facets.update(callback)

Renders/updates the facet grid based on the current state, and returns the instance.

Getters

facets.numColumns()

Returns the number of columns in the grid.

facets.numRows()

Returns the number of rows in the grid.

facets.facets()

Returns an array of objects representing each facet.

facets.facetWidth()

Returns the width of the facets in the grid.

facets.getFacet(name)

Returns an object representing the facet with the specified name.

facets.isRagged()

Returns false if the grid is "complete" (i.e. the last row has an cell for every column). Otherwise returns true.