README

Flourish axes highlights

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. The minimum methods you will need to use is appendTo, chartLayout and update.

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. Adding a basic axis highlight container

A basic implementation of an axis highlights container. See "Methods" for full configuration.

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

This basic implementation appends the axes highlights to a container (target_node). 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).

Methods

animationDuration

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

appendPatternsTo

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.

appendTo

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.

chartLayout

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 module:

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

facetName

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

numberParser

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 date parsers and strings arent parsed). Expects a function.

offset

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

update

update highlights!

xDisabled

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

xExtendByStep

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.

yDisabled

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

yExtendByStep

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.

Usage no npm install needed!