@flourish/controls/README.md

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

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

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


## Basics

Initialise the control outside any function:

``` js
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:

``` js
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(container, [bounding_container])`

Appends the control to the `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.

## 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](https://github.com/kiln/flourish-ui-styles) to style the controls.