colejd / guify

A simple GUI for inspecting and changing JavaScript variables

guify

Demo | Docs

Guify is a runtime JS library that gives you a simple way to build a GUI for your JS projects. It pairs very well with three.js and p5.js. Consider it an opinionated take on dat.GUI.

Here are the big features:

• Bind any UI component to any variable. Guify supports arbitrary text inputs, colors, ranges, file inputs, booleans, and more.
• Guify is easy to graft onto any page and integrate with your existing JS code. Just point your components at the variables you already have:

  var someVariable = 0;
  guify.Register([{
      {
          type: 'range',
          object: this, property: 'someProperty',
          label: 'Some Property',
          min: 0, max: 20, step: 1
      },
  }])

• Give it that "web app" look with an optional header bar and easy toast notifications.
• Style it however you'd like. You can use one of three built-in themes, or build your own to get exactly the look you want.

---

Installation

Below are some common ways to integrate Guify with your setup.

Quick Start (Browser)

To integrate on an existing page, you can use the transpiled version in /lib, either by including it with your files or using a CDN:

<script src="https://unpkg.com/[email protected]/lib/guify.min.js"></script>

This adds a guify function at the global level, which you can use to construct the GUI. For example:

<script src="https://unpkg.com/[email protected]/lib/guify.min.js"></script>

<script>
    var gui = new guify({ ... })
    gui.register([ ... ])
</script>

See the Usage guide below for more details. example.html also demonstrates this pattern.

Quick Start (NPM)

First, install with NPM: npm install --save guify

Then you can import using either require or import depending on your preference:

// ES6
import guify from 'guify'

// Require
let guify = require('guify');

Then you can make a quick GUI this way:

var gui = new guify({ ... });
gui.Register([ ... ]);

See the Usage guide below for more details.

Quick Start (React)

Check out the unofficial React port.

---

Usage

Once you have Guify available to construct in your project, make a guify instance:

var gui = new guify({
    title: "Some Title",
});

The various controls in Guify are called "components". You can feed component definitions to Guify as follows:

gui.Register([
    { // A slider representing a value between 0 and 20
        type: 'range', label: 'Range',
        min: 0, max: 20, step: 1,
        onChange: (value) => {
            console.log(value);
        }
    },
    {
        type: 'button', label: 'Button',
        action: () => {
            console.log('Button clicked!');
        }
    },
    {
        type: 'checkbox', label: 'Checkbox',
        onChange: (value) => {
            console.log(value);
        }
    }
]);

You can also bind components representing a value to your JS variables instead of using an onChange() handler. For example:

var someNumber = 10;
gui.Register([
    { // A slider representing `someNumber`, constrained between 0 and 20.
        type: 'range', label: 'Range',
        min: 0, max: 20, step: 1,
        object: this, property: 'someNumber'
    },

There are many points of customization here. See the docs at /docs/api.md. A much more robust example can also be found at example.html.

Building This Package

If you want to build this package, you can run npm install and then npm run build:prod, which will create /lib/guify.min.js.

NPM commands:

• build:prod: Creates /lib/guify.min.js, the default script used by this package.
• build:dev: Creates /lib/guify.js.
• develop: Runs build:dev and serves the /example directory as a static web page.

---

Changelog

See changelog.md.

License

MIT license. See license.md for specifics.

Credit

This package is largely based on control-panel. For setting this up, I used webpack-library-starter.

Alternatives

• dat.GUI
• Control-Panel
• Oui

guify's Issues

The class named ".guify-container" fill the whole webpage so all of div component can not be touched.

The css value of class ".guify-container" :
.guify-container {
position: absolute;
left: 0;
width: 100%;
height: 100%;
z-index: 9999;
}
All of Div can not be triggered because of the "height: 100%".

Update toolchain to modern Babel configuration

Disallow keyboard interaction with disabled components

Automate testing with Actions

Automate NPM publishing with Actions

React version

Hey! I loved your lib and decided to create a thin React wrapper around it.

https://github.com/dbismut/react-guify

Maybe you’d like to mention it in the ReadMe?

Also, I may have overlooked some options but there’s no way to update panel or component options after initialization, is there?

How to add/remove components at run-time?

And how to disable components? For example buttons...

Checkbox Bug - Consecutive Checkboxed trigger first registered Checkbox

Hi There,

First of all thanks for that great UI contribution. Was searching for something like this for a long time.
I think there is a bug with the checkboxes.
Every checkbox after the first registered do not work, but instead trigger the first checkbox that was registered.

This bug also happens in your demo. Just try to check the second checkbox.

Cheers,
bel

How to update label?

I am trying to implement on-the-fly multi-language support by changing labels.
I tried the following but it didn't work. Does anyone know a solution?

	var web_text = ['label1','label2']
	gui2.Register([
		{
			type: 'select',
			label: web_text[0],
			options: ["MANUAL", "AUTOGAIN", "AUTOEXPOSURE"],
			onChange: (data) => {
				console.log(data);
			}
		}
	});

	// other part of the code
	web_text[0] = 'new label in other language'

Cant set overflow to hidden ?

I cant remove the scrollbars on the gui not sure why.

Event trigger on the mouse up event

In the current example, the "onChange" event is triggered whenever the slider is moved.
Is it possible to make it triggered on the mouse up event?

Error when constructing guify instance

I'm just getting started with guify, but I run into an issue when using the npm version. The default export is not a constructor:

All I'm doing is this:

import guifiy from "guify";

const gui = new guifiy();

And I get the error _guify.default is not a constructor.

Here's a demonstration of the bug:

https://codesandbox.io/s/eloquent-williams-vlqze?file=/src/index.js

This is using guify 0.15.1, the last version as of now.

Variable binding does not work

I was testing the following example code but found that the variable binding is not working.

When I run the code, "Stepped Range" starts with 8 instead of 64 and the log message in the call-back always prints 64 regardless of the slider value. Do you see any problem with the code?

	var container_gui = document.getElementById("gui-container");
	container_gui.style.display = "none";
	// Create the GUI
	var gui2 = new guify({
		theme: 'dark', // dark, light, yorha, or theme object
		align: 'right', // left, right
		width: 300,
		barMode: 'none', // none, overlay, above, offset
		panelMode: 'inner',
		opacity: 0.95,
		root: container_gui,
		open: false
	});

	var steppedNumber = 64;
	gui2.Register({
		type: 'range',
		label: 'Stepped Range',
		min: 8, max: 64, step: 8,
		object: this, property: "steppedNumber",
		onChange: (data) => {
			console.log(steppedNumber);
		}
	});

Edit 1:
I have track the problem and found the opts.object is undefined in the following code.

guify/src/gui.js

Line 190 in beae4ec

if(opts.object && opts.property) {

"object: this" was not defined as the code was in a module.

'<script type="module" src="./build/abovecode.js"></script>'

Is there a way to fix this without moving the code out of the module? It should be a module due to "import".