@flourish/controls/README.md

# Flourish controls

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

## How to install

`npm install -s @flourish/controls`

Add one or more control objects to your template state as well an object for the controls container

``` js
export var state = {
	controls_container: {},
	buttons_control: {
		control_type: "buttons"
	},
	dropdown_control: {
		control_type: "dropdown"
	},
	...
}
```

Add settings for the controls container in `template.yml`.

``` yaml
  - property: controls_container
    import: "@flourish/controls/container"
```

This will add a controls container alignment and spacing options in the settings.

Then import `@flourish/controls` for each controls instance.

``` yaml
- property: buttons_control
    import: "@flourish/controls"
- property: dropdown_control
    import: "@flourish/controls"
```

## Basics

Initialise the controls container and individual controls outside any function:

``` js
import { createControlsContainer, createControls } from "@flourish/controls";

var buttons_control = initControls(state.buttons_control);
var dropdown_control = initControls(state.dropdown_control)

var controls_container = createControlsContainer(state.controls_container)
	.appendTo(layout.getSection("controls"))
	.add([buttons_control, dropdown_control]);

```

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 buttons_control = init(state.buttons_control, getParser, getFormatter);
```

Add an on change handler to each controls instance: `buttons_control.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: `buttons_control.options(options).update();`. If you're using this module alongside `@flourish/ui-styles` you should call the update method from the ui-styles object first (this will ensure the dropdown icon correctly matches the size and color styles set in the ui-styles panel).

## Controls container methods

### `appendTo(parent_container)`

Appends the controls container to the `parent_container` DOM node (this should usually be `layout.getSection("controls")`). Returns the controls container object.

### `add([controls_instances])`

Takes an array of controls instances and appends these to the controls container. Returns the controls container object.

### `update()`

This updates the controls container and all the appended controls instances (calling their individual `update()` methods). Returns the controls container object.

## Controls methods

### `appendTo(parent_container)`

Appends the control to the `parent_container` DOM node and injects CSS into the `head` if necessary.

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