@flourish/chart-layout

Flourish chart layout

Create axes and plotting regions for data

How to install

npm install -s @flourish/chart-layout

Add objects to your template state representing the x and/or y and/or y2 axes, and optionally also the background area. For example:

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

Import the corresponding settings into your template.yml, e.g.:

- X axis
- property: x
  import: "@flourish/chart-layout/x"
- Y axis
- property: y
  import: "@flourish/chart-layout/y"
- Y2 axis
- property: y2
  import: "@flourish/chart-layout/y"
- Chart background
- property: chart_bg
  import: "@flourish/chart-layout/background"

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/chart-layout";
var container = select(layout.getSection("primary")).select("svg"); // see @flourish/layout
var props = { x: state.x, y: state.y, y2: state.y2, background: state.chart_bg };
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([options])

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

Properties of optional options object can be used to modify the update method's functionality. If skip_rendering is true then distances, margins and ticks will be recalculated and any changes to the chart offset will be applied, but the chart components will not be re-rendered. If a margins object is supplied and any of its top, right, bottom or left properties are not undefined then the corresponding margin will be fixed to that value, rather than calculated.

The Data methods of chart_layout

These three 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 primary (left) vertical axis.

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

Gets or sets the data associated with the secondary (right) vertical axis.

The Scale methods of chart_layout

These three 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 the chart_layout.chart container, and particularly the chart_layout.data_background or chart_layout.data_foreground containers. However, if the options 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 options 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([options])

Gets a scale function for calculating x-coordinates.

chart_layout.yScale([oprions])

Gets a scale function for calculating primary y-coordinates.

chart_layout.y2Scale([options])

Gets a scale function for calculating secondary y-coordinates.

Width, height and margin functions and properties of chart_layout

chart_layout.height([value])

If value is specified, sets the total height of the chart_layout area and returns the chart_layout instance. If value is null, the height of the bounding rectangle of chart_layout.svg is used (if the plotAspect hasn't been set). If value is undefined returns the calculated total height of the chart_layout area. Calling the plotAspect method with a value will lead to a recalculation of the height.

chart_layout.plotAspect([value])

If value is specified, sets the aspect ratio of the plot area and returns the chart_layout instance. If value is null, the plotAspect is unset and the aspect is determined implicitly from the width, height and margins. If value is undefined returns the calculated or previously set plot aspect ratio. Calling the height method with a value will lead to a recalculation of the plot aspect.

chart_layout.width([value])

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

chart_layout.margins()

Returns an object containing the top, right, bottom and left margins as used the last time update was called. These can also be read individually as properties of the method, ie chart_layout.margins.top, chart_layout.margins.right, chart_layout.margins.bottom and chart_layout.margins.left.

chart_layout.plot_height

Read-only plot height of the chart_layout area.

chart_layout.plot_height

Read-only plot width of the chart_layout area.

The Ticks methods of chart_layout

chart_layout.xTicks()

Returns a frozen array of frozen objects, where each object includes properties of a single tick mark/label pair that was drawn on the x axis the last time update was called.

chart_layout.yTicks()

Returns a frozen array of frozen objects, where each object includes properties of a single tick mark/label pair that was drawn on the y axis the last time update was called.

chart_layout.y2Ticks()

Returns a frozen array of frozen objects, where each object includes properties of a single tick mark/label pair that was drawn on the y2 axis the last time update was called.

chart_layout.xTicks.autoLabelSpace([value, [unit]])
chart_layout.yTicks.autoLabelSpace([value, [unit]])
chart_layout.y2Ticks.autoLabelSpace([value, [unit]])

All three *Ticks methods outlined above have a sub-method that can be used to define how the maximum space for tick labels is calculated when the Flourish-user specifies the "auto" option for the relevant tick_label_space_mode property. These methods recognise up to two parameters. value specifies the magnitude of the margin in the given unit. Recognised units are "px", "rem" and "fraction". In the case of "fraction", this refers to the height (for the x method) or width of the chart-layout instance. If only a value is specified when calling one of these methods, the unit is assumed to be "px". The instance is returned in either case. If value is not specified when calling one of these functions then an object is returned that includes the current choice of unit and the calculated values for all three options based on the currently specified value and unit combination.

The space being defined is a height for the x axis and a width for the y and y2 axes. Labels that are too long for the defined space may be automatically shorted (with trailing characters replaced by a single "…" character). However, if the labels are oriented at right angles to the relevant spatial dimension, no shortening will occur.

The Title methods of chart_layout

chart_layout.xTitle()

Returns the computed title text for the x axis.

chart_layout.yTitle()

Returns the computed title text for the y axis.

chart_layout.y2Title()

Returns the computed title text for the y2 axis.

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.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.offsetTop([value])

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

chart_layout.offsetLeft([value])

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

chart_layout.xAutoTitle([value])

If value is specified, sets the title text to be used for the x axis to value when the Flourish user choses auto for the title_mode.

chart_layout.xDatetimeParse([func])

If func is specified, sets the parsing function to be applied when the Flourish user inputs dates in string format in the settings for the x axis. Currently this means the min and max for the date range.

chart_layout.xFormat([func])

If func is specified, sets the formatting function to be applied to the tick formats on the x axis. The func function is called for every tick on the axis on update with the ticks own value as the only argument. The value returned is then used as the printed tick label. If chart_layout.xFormat is never called with a func or func is falsy (but not undefined) the default formatting function, function(value) { return "" + value; }, is used.

chart_layout.xZeroAxis([value])

If value is specified and is truthy then the x axis will include 0 if the data is numeric and the axis linear, regardless of the xData values. User-set min and max settings can overcome this restriction.

chart_layout.yAutoTitle([value])

If value is specified, sets the title text to be used for the y axis to value when the Flourish user choses auto for the title_mode.

chart_layout.yDatetimeParse([func])

If func is specified, sets the parsing function to be applied when the Flourish user inputs dates in string format in the settings for the y axis. Currently this means the min and max for the date range.

chart_layout.yFormat([func])

If func is specified, sets the formatting function to be applied to the tick formats on the primary y axis. The func function is called for every tick on the axis on update with the ticks own value as the only argument. The value returned is then used as the printed tick label. If chart_layout.yFormat is never called with a func or func is falsy (but not undefined) the default formatting function, function(value) { return "" + value; }, is used.

chart_layout.yZeroAxis([value])

If value is specified and is truthy then the primary y axis will include 0 if the data is numeric and the axis linear, regardless of the yData values. User-set min and max settings can overcome this restriction.

chart_layout.y2AutoTitle([value])

If value is specified, sets the title text to be used for the y2 axis to value when the Flourish user choses auto for the title_mode.

chart_layout.y2DatetimeParse([func])

If func is specified, sets the parsing function to be applied when the Flourish user inputs dates in string format in the settings for the y2 axis. Currently this means the min and max for the date range.

chart_layout.y2Format([func])

If func is specified, sets the formatting function to be applied to the tick formats on the secondary y axis. The func function is called for every tick on the axis on update with the ticks own value as the only argument. The value returned is then used as the printed tick label. If chart_layout.y2Format is never called with a func or func is falsy (but not undefined) the default formatting function, function(value) { return "" + value; }, is used.

chart_layout.y2ZeroAxis([value])

If value is specified and is truthy then the secondary y axis will include 0 if the data is numeric and the axis linear, regardless of the y2Data values. User-set min and max settings can overcome this restriction.