@flourish/chart-layout

Flourish chart layout

Create axes and plotting regions for data

How to install

npm install -s @flourish/chart-layout

Add (eg) x and y objects to your template state:

export var state = {
	x: {},
	y: {},
	...
}

Import @flourish/chart-layout into your template.yml settings.

How to use

Initialise a chart-layout object for every chart you want to create. You need a container SVG element (a node, a d3-selection or a CSS selector string) which you will add the chart to and an object containing the relevant state properties. For example

import createChartLayout from "@flourish/layout";
var container = select(layout.getSection("primary")).select("svg"); // see @flourish/layout
var props = { x: state.x, y: state.y };
var chart_layout = createChartLayout(container, props);

This adds a number of SVG elements to the container and returns an object, chart_layout.

Properties of chart_layout

chart_layout.chart

A d3-selection of the route SVG element created by chart_element.

chart_layout.container

A d3-selection of the container specified at the time of creation.

chart_layout.data_background

A d3-selection of an area created within the chart_element that is suitable for adding data to. Data elements placed within this container will appear below any visible gridlines.

chart_layout.data_foreground

A d3-selection of an area created within the chart_element that is suitable for adding data to. Data elements placed within this container will appear above any visible gridlines.

The update method of chart_layout

chart_layout.update()

Call this method to redraw (with animation) the chart layout components based on the current set of stored values and state properties. Returns the chart_layout instance.

The Data methods of chart_layout

These two methods expect values to be either an array or an instance of a Flourish enhanced array (see @flourish/enhanced-array). In the case of the former, an optional accessor method can be included in order to, for example, extract a specific property from each object in an array of objects. The stored data is used to determine both the type of axis (numeric or ordinal) and its domain. If values is an enhanced array then a numeric axis will be constructed for the relevant dimension if it is a numeric enhanced array and an ordinal scale will be constructed if it is a string enhanced array. If values is a regular array then the type of the first element (after application of the accessor function) will be used to determine whether the scale should be numeric or ordinal.

If values is undefined, an enhanced array will be returned that is either the original one passed in or one derived from the regular array passed in. When values is defined, the chart_layout instance is returned so that methods can be chained.

chart_layout.xData([[values], accessor])

Gets or sets the data associated with the horizontal axis.

chart_layout.yData([[values], accessor])

Gets or sets the data associated with the vertical axis.

The Scale methods of chart_layout

These two methods get d3-scales suitable for plotting data. Because this module uses SVG transforms then, in general by default, the scale will be useful for plotting data only within chart_layout.chart container, and particularly the chart_layout.data_background or chart_layout.data_foreground containers. However, if the form object is present and has a global property that is truthy, the scale is suitable for use outside the chart_layout.chart object (and, generally, not inside it), anywhere that has the same calculated transform as chart_layout.container. The domain_only property of form specifies that a suitable range for the scale should not be calculated. This can be useful if you want to extract the domain for one axis before you specify the data for the other.

chart_layout.xScale([form])

Gets a scale function suitable for calculating x-coordinates.

chart_layout.yScale([form])

Gets a scale function suitable for calculating y-coordinates.

Other methods of chart_layout

All the methods below act like both getters and setters. When a value is specified the return value is always the chart_layout instance to allow for method chaining. When a value is not specified, the return value is the currently saved value associated with that property.

chart_layout.animationDuration([value])

If value is specified, sets the duration of animations (in milliseconds) that take place when chart_layout.update is called.

chart_layout.clip([value])

If value is specified, sets whether (truthy) or not (falsy) the data is clipped to the bounds of the axes.

chart_layout.height([value])

If value is specified, sets the total height of the chart_layout area. If value is any falsy value other than undefined, the height of the bounding rectangle of chart_layout.container is used.

chart_layout.identifier([value])

If value is specified, sets the charts identifier to that value. This is used to make an id for clipping purposes so should not be used on more than one chart_layout instance on a page and should match the rules for HTML id attributes. If a value has never been passed to this method then a value that should be unique is used. It takes the form of the string "fl-chart-layout-" with a number appended.

chart_layout.width([value])

If value is specified, sets the total width of the chart_layout area. If value is any falsy value other than undefined, the width of the bounding rectangle of chart_layout.container is used.

chart_layout.xOffset([value])

If value is specified, sets the horizontal transform applied to the whole chart_layout instance (defaults to 0).

chart_layout.yOffset([value])

If value is specified, sets the vertical transform applied to the whole chart_layout instance (defaults to 0).