selecton/README.md

Selecton.js combines a searchbar and a dropdown menu with nested child lists.

![selecton.js logo](assets/selecton_logo.svg)
Selecton.js combines a search bar and a drop-down menu with nested child lists. It helps you to display hierarchical order within your drop-down menus. Selecton.js is completely object-based, meaning that all values are represented as objects.
See example [here](https://bl.ocks.org/niekes/e7f635c99b2b07f330164014c5b58389).

## Installing

If you use npm, `npm install selecton`. You can also download the [latest release](https://github.com/Niekes/selecton/releases). Otherwise use [unpkg](https://unpkg.com/selecton/) to get the latest release. For example:

```html
<script src="https://unpkg.com/selecton/build/selecton.js"></script>
```

For a specific version:
```html
<script src="https://unpkg.com/selecton@version/build/selecton.js"></script>
```

For the minified version:

```html
<script src="https://unpkg.com/selecton@version/build/selecton.min.js"></script>
```

For the css:

```html
<link rel="stylesheet" type="text/css" href="https://unpkg.com/selecton@version/build/css/selecton-light.min.css">
```

```html
<link rel="stylesheet" type="text/css" href="https://unpkg.com/selecton@version/build/css/selecton-dark.min.css">
```

Note: *dark* and *light* means on what background they appear better. If you want to change the styles, you should clone the repo and take a look at the sccs folder.

## Import

```js
import {default as Selecton} from 'selecton';
```

## Build

Clone or download the repository. Run `npm install` to install all dependencies. To manipule the css and to make changes to the source code run `npm run watch` and `gulp` (in different tabs).

## Quick-start

```html

<!-- add css -->
<link rel="stylesheet" type="text/css" href="selecton.css" />

<!-- add container -->
<div id="selecton-container"></div>

<!-- add selecton.js -->
<script src="selecton.js"></script>

<script>
    // declare data
    var data = [{key:'A'}, {key:'B'}, {key:'C'}];

    // define order of items in the input field (optional)
    var data = ['B', 'A', 'C'];

    // create new selecton instance and pass the config as an object
    var selecton = new Selecton({
        el: '#selecton-container'
    });

    // pass the data and the order to selecton
    selecton.update(data, order);

    // listen for changes
    selecton.on('change', function(data){
        console.log(data); // only the selected items, alternatively use selecton.getData()
    });
</script>
```
## Configuration and options
### Constructor config

config | description | required | type | default
--- | --- | --- | --- | ---
`el` | css selector of element in which selecton will appear | ✅ | string |
`key` | which property is used to bind the data | ❌ | function | `function(d){ return d.key; }`
`renderInputItem` | render input item | ❌ | function | `function(d){ return d.key; }`
`renderDropdownItem` | render drop-down item | ❌ | function | `function(d){ return d.key; }`
`open` | drop-down opens up on start | ❌ | boolean | false
`showHierachyButton` | show hierarchy button in input item | ❌ | boolean | true
`showRemoveButton` | show remove button in input item | ❌ | boolean | true

### Item properties

property | description | required | type | default
--- | --- | --- | --- | ---
`key` | this key is used to bind the the data to the DOM-element. this key has to be unique within the parent. | ✅ | string |
`color` | if color is specified, the color is used to colorize the input item | ❌ | string | '#1e90ff'
`selectable` | selectable decides if the item is click-able and search-able | ❌ | boolean | true
`closed` | does not show up on start | ❌ | boolean | true
`selected` | indicated if the item is selected | ❌ | boolean | false

The following properties are used internally by selecton.js and should not be overwritten:

property | description | type
--- | --- | ---
`_depth_` | depth level in hierarchy | number
`_parent_` | key of parent | string
`_search_` | search string to highlight search match | string
`_temporarilyHighlighted_` | property to highlight item temporarily | boolean
## Methods
Each selecton instance comes with some useful methods:

`selecton.update()` updates the the input and the drop-down menu

`selecton.on('change', callback)` Listen for changes

`selecton.on('keyup', callback)` Listen for keyup event

`selecton.getData()` returns the whole data set with the computed values as objects

`selecton.getSelectedItems()` returns the selected items as objects

## Dependencies

Selecton.js uses [d3-selection](https://github.com/d3/d3-selection) for the data-binding and [d3-drag](https://github.com/d3/d3-drag) for the dragging.

## Browser support

Chrome, Safari, Firefox, IE11+