freeman-lab / control-panel

embeddable panel of inputs for parameter setting

control-panel

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, but streamlined, simplified, and written as a npm module for use with browserify.

LIVE DEMO

---

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.

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,

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

{'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

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

access its current value using

panel.state['my checkbox']

react port

This project has been ported to work with React and is available as 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
• datgui

control-panel's Issues

Missing ',' in README example

In https://github.com/freeman-lab/control-panel#example

Should be:
{type: 'select', label: 'select one', options: ['option 1', 'option 2'], initial: 'option 1'} ,{type: 'multibox', label: 'check many', count: 3, initial: [true, false, true]}

Thanks for a great tool!

Stop event propagation

I end up typing this in nearly every example, otherwise the events leak through and, for example, pan the underlying view even when I'm dragging a slider:

var el = document.querySelector('.control-panel');
var events = ['mousemove', 'click', 'mousedown', 'mouseup'];
for (var i = 0; i < events.length; i++) {
  el.addEventListener(events[i], function(ev) {
    ev.stopPropagation();
  });
}

Note to self: make a PR for this! I wonder what the full set of events stopped from propagating should be.

Make panel closable.

Hi freeman,

Nice project and thank you for your work! I just use it and it is perfect except I think one little Close Panel button like dat-gui or dis-gui would be good for preview demo when editing.

I show you a picture for this.

npm WARN deprecated [email protected]: Use uuid module instead

Webpack is unsupported?

When trying to use control-panel with Webpack, I get:

Uncaught Error: Cannot find module "fs"

and

./node_modules/control-panel/index.js Module not found: Error: Can't resolve 'fs' in '$PATH_TO_PROJECT/node_modules/control-panel'.

This seems to be a known problem with other repos (see here, for example), but the solutions provided for those repos (namely, adding node: { fs: "empty: } to the webpack.config.js) do not seem to work — trying that results in a new error: Uncaught TypeError: fs.readFileSync is not a function.

Following up on that error leads to information that fs.readFileSync will never truly work in the browser, as it is a Node function (see here).

Prama finds

Hi @freeman-lab, very nice lib!
I was really laughing hard when I saw this repo, as recently I’ve spent 3 days on exact functionality in prama (parameters manager). Funny thing is that API is literally the same. But prama is nowhere close to the nice style of control-panel.
Therefore I can just share bugs and features I stumbled upon.
First off, it seems range slider does not work in iOS. I used Lea Veorou’s multirange for that purpose.
Second, it would be really nice to have control panel draggable, because some components, like gl-spectrum are full-screen. Though that task can be solved by user.
Third, I found that saving and loading current state to sessionStorage might come in handy at debugging, to avoid setting up parameters anew each page reload.
Wished I knew that package 3 days before!

How to remove panel or components at run-time?

Field types and improvements

Hi!

I started playing with various fields, and have found that sometimes it is useful to have additional field types:

• textarea - for large text content, like description, tagline, title, data-uri encoded image, svg etc. In conjunction with autosize it is even better than usual type='text'. As an option - replace default text input with textarea and autosize. API won’t change, for the end user there will be no difference, but UX will be smoother.
• radio - an alternative for select. It may work better for small sets, as it shows all possible options at once, which makes interaction easier and faster.
• custom - renders custom user HTML. That could be dividers, section titles, custom inputs, like vecN inputs, unit inputs (number + unit select), reset button, file input etc. It is quite easy to implement, and covers the rest of possible use-cases. Also that allows for extending control-panel with additional fields from other packages.

Any thoughts?

Control-panel in Angular app

Hi

I'm using control-panel in an angular application in a component using Three.js
I get the following error on the console:

core.js:1448 ERROR TypeError: fs.readFileSync is not a function at new Plate (index.js:29) at Plate (index.js:15)

Any advice how to resolve this?

Best
stefan

mobile support

There's at least one issue with viewing the control panel on iOS/android. This issue can be a place to track it, as well as any others that we find.

• range slider doesn't work because it's not supported on iOS, we should be able to use multirange instead (thanks @dfcreative for the tip!)

Direct value input for range control

I know this library is somehow unmaintained, well, in case that someone still watches it, i'd like to ask whether there's simple way to make value of range input direcly editable.

Does this library support collapsing and grouping?

Sometimes the variables can be a lot, so grouping and collapsing of the inputs can be really useful.

Here is an example oh what I'm talking about:

http://www.curious-creature.com/pbr_sandbox/

dat.gui of course supports it and it's very useful, any plan for this library to support it?

color picker z index?

When two control panels are placed next to each other but non-overlapping, the color picker from one panel can be hidden by the other panel. A few attempts at playing with the z-index failed. Probably something tricky with the positioning settings. Big 👍 if anyone can figure this out =)

Handles seem too small for touch events in range sliders

If your touch event falls onto the rail instead of the little grabber, it has no effect on touch devices. Solutions either seem to be to drop the built-in element with this undesirable behavior or to make the grabbable area slightly wider.

API for updating state

Hey @freeman-lab,

I'm playing around with some ideas to improve the authoring process for Idyll, and one of them is to automatically give the user a control panel that hooks into the reactive state (see idyll-lang/idyll#320).

This is working great, but it only updates in one direction. Is there a way to programmatically update the control panel's state?

make panel draggable?

As pointed out by @dfcreative, for some use cases it might be really useful to be able to drag the panel around the screen. Unclear whether we want to add that to this module, or just put together a nice simple demo showing others how to make the panel draggable by composing with other modules (assuming it's simple!).