Flourish controls

Add interchangeable controls (dropdown, buttons or slider) to a page.

How to install

npm install -s @flourish/controls

Add one or more control objects to your template state:

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

Import @flourish/controls into your template.yml settings.

Basics

Initialise the control outside any function:

import initControls from "@flourish/controls";
var control = initControls(state.controls);

You can also pass in optional functions for getting parsing and formatting functions. The former is required if you want to use user input and the user is using "," as the decimal separator. The latter is required if you want to format numbers to use "," as a decimal separator. For example:

import initLocalization from "@flourish/number-localization";
import initFormatter from "@flourish/number-formatter";
import state from "../core/state";

localization = initLocalization(state.localization);
formatter = initFormatter(state.formatting);

function getParser() {
    return localization.getParser();
}

function getFormatter() {
    return formatter(localization.getFormatterFunction());
}

var control = init(state.controls, getParser, getFormatter);

Append the control to a container and add an on change handler: controls.appendTo(container).on("change", update);. This is usually done in the draw function.

In update you typically want to update the set of options and then call the controls own update method: controls.options(options).update();.

Methods

appendTo(parent_container, [bounding_container])

Appends the control to the parent_container DOM node and injects CSS into the head if necessary. The optional bounding_container makes sure the dropdown list will never overflow outside that container.

Returns the control object.

getSortedIndex()

Returns the index of the currently chosen value in a sorted version of the options array.

index([i])

With no argument returns the (unsorted) index of the currently selected option. If i is specified and corresponds to an index into the options array, sets the currently selected option to i. Returns the control object.

n_options()

Returns the current number of options.

on(event, callback)

Add callback to the list of event handlers. Currently the only supported event is "change". Returns the control object.

options([arr])

With no argument returns a copy of the current list of options displayed by the current control. With an array, replaces the current options with a copy of arr and returns the control object.

remove()

Removes the control (and its resize event handler) from the DOM. Returns the control object.

trigger(event)

Calls all the handlers assigned to event and returns the control object. Currently the only supported event type is "change".

update()

Rebuilds the control with latest settings. Returns the control object.

value([val])

With no argument returns the string value of the currently selected option. With val present changes the current index to match that of val in the options array and returns the control object. If val is not in the options array then nothing is changed but the control object is still returned.

getNode()

Returns the container of the control that has been created. It will have a class of "fl-controls-container"

Styling the controls

The controls have very basic styling. You can overwrite these styles with your own css and styling. We recommend using @flourish/ui-styles to style the controls.