Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/freeman-lab/control-panel

embeddable panel of inputs for parameter setting
https://github.com/freeman-lab/control-panel

Last synced: 4 days ago
JSON representation

embeddable panel of inputs for parameter setting

Awesome Lists containing this project

README 

        
# control-panel



[![NPM version][npm-image]][npm-url]

![experimental][experimental-image]

[![js-standard-style][standard-image]][standard-url]



Embeddable panel of inputs for adding parameter selection to your app or visualization. Modern and minimalist design. Fully encapsulated module including JS and CSS. Can easily be added to any app or page. Heavily inspired by [`dat-gui`](https://github.com/dataarts/dat.gui), but streamlined, simplified, and written as a npm module for use with browserify.



**[`LIVE DEMO`](http://control-panel.surge.sh)**



[![themes](images/themes.png)](http://control-panel.surge.sh)



----------------



> Supports the following input types



> `range` • `checkbox` • `text` • `color` • `button` • `interval` • `select`



----------------



> Includes the following themes



> `dark` • `light`



Want to contribute a new theme or input type? Submit a PR!



## install



Add to your project with



```

npm install control-panel

```



## example



Create a panel with four elements and add to your page in the top right.



```javascript

var control = require('control-panel')



var panel = control([

  {type: 'range', label: 'my range', min: 0, max: 100, initial: 20},

  {type: 'range', label: 'log range', min: 0.1, max: 100, initial: 20, scale: 'log'},

  {type: 'text', label: 'my text', initial: 'my cool setting'},

  {type: 'checkbox', label: 'my checkbox', initial: true},

  {type: 'color', label: 'my color', format: 'rgb', initial: 'rgb(10,200,0)'},

  {type: 'button', label: 'gimme an alert', action: function () {alert('hello!');}},

  {type: 'select', label: 'select one', options: ['option 1', 'option 2'], initial: 'option 1'},

  {type: 'multibox', label: 'check many', count: 3, initial: [true, false, true]}

], 

  {theme: 'light', position: 'top-right'}

)

```



## usage



#### `panel = control([input1, input2, ...], [opts])`



The first argument is a list of inputs. Each one must have a `type` and `label` property, and can have an `initial` property with an initial value. For example,



```javascript

{type: 'checkbox', label: 'my checkbox', initial: true}

```



Each `type` must be one of `range` • `input` • `checkbox` • `color` • `interval` • `select`. Each `label` must be unique. 



Some types have additional properties:

- Inputs of type `range` can specify a `min`, `max`, and `step` (or integer `steps`). Scale can be either `'linear'` (default) or `'log'`. If a log scale, the sign of `min`, `max`, and `initial` must be the same and only `steps` is permitted (since the step size is not constant on a log scale).

- Inputs of type `color` can specify a `format` as either `rgb` • `hex` • `array`

- Inputs of type `button` can specify an `action` callback. Button inputs are not reflected in the state and do not trigger an `'input'` event.

- Inputs of type `interval` obey the same semantics as `range` inputs, except the input and ouput is a two-element array corresponding to the low/high bounds, e.g. `initial: [1, 7.5]`.

- Inputs of type `select` can specify a list of options, either as an `Array` (in which case the value is the same as the option text) or as an object containing key/value pairs (in which case the key/value pair maps to value value/label pairs).

- Inputs of type `multibox` can specify a number of checkboxes, either by providing a `count` or a list of `names` from which the number will be inferred, in which case the color of each box and a text name can also be provided as lists `colors` and `names`



The following optional parameters can also be passed as `opts`

- `root` root element to which to append the panel

- `theme` can specify `light` • `dark` or provide an object (see [`themes.js`](themes.js) for format)

- `title` a title to add to the top of the panel

- `width` width of panel in pixels

- `position` where to place the panel as `top-left` • `top-right` • `bottom-left` • `bottom-right`, if `undefined` will just use relative positioning



#### `panel.on('input', cb(data))`



This event is emitted every time any one of the inputs change. The callback argument `data` will contain the state of all inputs keyed by label such as:



```javascript

{'my checkbox': false, 'my range': 75}

```



#### `panel.state`



Access the current value of any input via its label, i.e. if you made the input



```javascript

{type: 'checkbox', label: 'my checkbox', initial: true}

```

access its current value using



```javascript

panel.state['my checkbox']

```



#### react port



This project has been ported to work with React and is available as [react-control-panel](https://github.com/ameobea/react-control-panel) on NPM.  The visual appearance is identical to that of the original, and some features have been added including externally managed state and an ES6 Proxy-based API for reading/writing the UI state remotely.



#### see also



- [oui](https://github.com/wearekuva/oui)

- [datgui](https://github.com/dataarts/dat.gui)



[npm-image]: https://img.shields.io/badge/npm-v1.3.4-lightgray.svg?style=flat-square

[npm-url]: https://npmjs.org/package/control-panel

[standard-image]: https://img.shields.io/badge/code%20style-standard-lightgray.svg?style=flat-square

[standard-url]: https://github.com/feross/standard

[experimental-image]: https://img.shields.io/badge/stability-experimental-lightgray.svg?style=flat-square