Flourish axes highlights

This module lets users add highlights to flourish-chart-layout (or flourish-axes) axes.

Getting started

1. Installation

npm install --save @flourish/axes-highlights

2. Add settings and state

const state = {
    axes_highlights: {} // Add any properties to this object to override the default settings
}

# template.yml
- property: axes_highlights
  import: "@flourish/axes-highlights"

3. Initialize the axes highlights

import initAxesHighlights from "@flourish/axes-highlights";
var axes_highlights = initAxesHighlights(state.axes_highlights);

4. Update axis highlights

In the template's update function (e.g. updateGraphic) you typically call the following methods:

let container = select(...);

axes_highlights
    .appendTo(container)
    .chartLayout(chart_layout)
    .update();

The minimum methods you will need to use is appendTo, chartLayout and update. See "Methods" for full configuration.

container is a D3 selection representing the element the highlights should be rendered in. You may need to import d3-transition in the module that makes the container selection, so that transitions are available. (Without this, the axis highlights might not display at all.)

This basic implementation appends the axes highlights to a container (container). If you want to append multiple axes highlights containers (for multiple facets for example) inside the same parent container, you can use the offset() method to position the axes highlights container (see example of implementation here). Axes highlights should be appended per facet, so for example in LBP and scatter it is called in the facet.js file for each facet group.

Methods

axes_highlights.animationDuration(number)

How long you want the animations to take. Expects a number.

axes_highlights.appendPatternsTo(selection)

Axis highlights can be rendered using an SVG pattern. Pass in the container you want the patterns to be appended to. It takes a d3 selection. If this is not called it will default to the appendTo container. As axes highlights are called per facet, it would be inefficient for a template with multiple facets to append the patterns to the facet container, as it would lead to patterns being defined more times than necessary. So if you are using a template that has multiple facets you should call appendPatternsTo just once in the draw function, passing it a container that wraps all of the facets (such as the svg) so that the same patterns are used for all axes highlights. If it is a template that doesnt have multiple facets you dont need to call this method as the default should work fine.

axes_highlights.appendTo(selection)

The parent element to append it to. We tend to use the fl-data-foreground group as the parent (if it exists). e.g. .appendTo(select(".fl-data-foreground")). Expects a d3 selection.

axes_highlights.chartLayout(chart_layout)

Specifies a chart layout (or axes) instance to attach the highlight to. Used for scales, margins, plot dimentions etc (should be one per facet).

Expects it to have the following properties, typically part of the @flourish/chart-layout (or @flourish/axes) module:

- xDatetimeParse
- yDatetimeParse
- margins
- plot_height
- plot_width
- xData
- yData
- xScale
- yScale

axes_highlights.facetName(string)

Name of facet, used to know if the highlight should apply to that facet or not. Expects a string.

axes_highlights.numberParser(fn)

Used to parse numbers e.g. localization.getParser(). Used to parse numbers when one of the axes is of type number. (If the axes are of type date we use the chart layout (or axes) date parsers and strings arent parsed). Expects a function.

axes_highlights.offset(object)

Adds offset to the axes highlights container. Expects an object containing an x and y property, eg. {x: 25, y: 10}.

axes_highlights.update()

Update highlights!

axes_highlights.xDisabled(boolean)

If you want x highlights to be disabled (e.g. in LBP when a chart doesnt have an x axis). Expects a boolean.

axes_highlights.xExtendByStep(boolean)

If you want x area highlights to be extended (e.g. in LBP the area goes beyond the exact x value because it is covering a grid of columns). Expects a boolean.

axes_highlights.yDisabled(boolean)

If you want y highlights to be disabled (e.g. in LBP when a chart doesnt have an y axis). Expects a boolean.

axes_highlights.yExtendByStep(boolean)

If you want y area highlights to be extended (e.g. in LBP the area goes beyond the exact y value because it is covering a grid of columns). Expects a boolean.