PaperGUI

A clone of dat.GUI using nice Polymer (1.0) paper elements. One of the advantages is that this makes it touch and mobile friendly. The API is intentionally similar, although not all features have been ported to PaperGUI.

Install

Building requires node, gulp and bower.

npm install gulp bower
npm install
npm run-script build

The dist folder contains the build. The paper-gui.html file is the only one you need if you want to use web component-style, synchronous import. Otherwise, you’ll need all 3 files in the dist folder as paperGUI.js loads the other two.

To try out the demo, run a webserver in the papergui root folder, eg:

python -m SimpleHTTPServer 8000

Then open http://localhost:8000/demo.html in a browser.

Usage

Basic usage

With very little code, PaperGUI creates an interface that you can use to modify variables, exactly like dat.GUI from which the below example is adapted.

<script type="text/javascript">
var FizzyText = function() {
  this.message = 'PaperGUI';
  this.speed = 0.8;
  this.displayOutline = false;
  this.explode = function() { ... };
  // Define render logic ...
};

/* Polymer elements are loaded asynchronously, we need to wait for
 * everything to be ready before creating the GUI. */
document.addEventListener('PaperGUIReady', function(e) {
  var text = new FizzyText();
  var gui = new PaperGUI();
  gui.add(text, 'message');
  gui.add(text, 'speed', -5, 5);
  gui.add(text, 'displayOutline');
  gui.add(text, 'explode');
};
</script>

<!-- Load the PaperGUI library and polyfills -->
<script type="text/javascript" src="dist/paperGUI.js"></script>

• The property must be public, i.e. defined by this.prop = value
• PaperGUI determines controller type based on a property’s initial value
• Press H to show/hide all GUI’s.

Importing PaperGUI as a web component

As shown above, the paperGUI.js script loads a polyfill and then imports the web components necessary for the PaperGUI library to work. Once it’s all set, it triggers a PaperGUIReady event. This allows to delay the loading of PaperGUI as much as possible.

Alternatively, you can skip the loader script call and use a (blocking) import directly. Add this at the top of your HTML:

<link rel="import" href="dist/paper-gui.html">

Note that in this case no PaperGUIReady event will be triggered, and the import will only work on web component-ready browsers as this bypasses support detection and polyfill loading.

Constrain

You can specify limits on numbers. A number with a min and max value becomes a slider. This is exactly the same API as dat.GUI.

gui.add(text, 'noiseStrength').step(5); // Increment amount
gui.add(text, 'growthSpeed', -5, 5); // Min and max
gui.add(text, 'maxSize').min(0).step(0.25); // Mix and match

You can also choose to select from a dropdown of values for both numbers and strings.

// Choose from accepted values
gui.add(text, 'message', [ 'pizza', 'chrome', 'hooray' ] );


// Choose from named values
gui.add(text, 'speed', { Stopped: 0, Slow: 0.1, Fast: 5 } );

Events

You can listen for events on individual controllers using an event listener syntax.

var controller = gui.add(fizzyText, 'maxSize', 0, 10);


controller.onChange(function(value) {
  // Fires on every change, drag, keypress, etc.
});

Note: the onFinishChange handler from dat.GUI is currently not supported.

Styling & positioning

PaperGUI exposes custom CSS properties and mixins (see Polymer documentation) through which you can change the colors and style of the UI.

Custom properties

Properties below can be used to modify the default colors of the PaperGUI interface and components:

Custom Property	Description
--paper-gui-accent-color	Accent used in the floating action button, toggle buttons, sliders, etc.
--paper-gui-accent-contrast-color	Applied to fonts and icons where the background uses accent color (buttons)
--paper-gui-background-color	Background color of the main dialog
--paper-gui-text-color	Main color for text inputs, labels, dropdown values, etc.
--paper-gui-ui-color	Used in components (borders, sliders, input placeholders, etc.)
--paper-gui-ui-secondary-color	Lighter shade of the above color, used in scrollbars and dividers

Example

In your main html file, declare the following custom-style to override default colors:

<style is="custom-style">
  paper-gui {
    --paper-gui-text-color: #808080;
    --paper-gui-background-color: white;
    --paper-gui-accent-color: #1976d2;
    --paper-gui-ui-color: #bbb;
    --paper-gui-ui-secondary-color: #f1f1f1;
  }
</style>

Mixins

If you need to further customize the edit button or the dialog, ie change their positioning or size, you can use dedicated custom mixins.

Custom Mixin	Description
--paper-gui-edit-button	Use this to customize the edit button
--paper-gui-dialog	Use this to override the size and positioning of the dialog (eg to place it in a different corner)

Example

In your main html file:

<style is="custom-style">
  paper-gui {
    --paper-gui-edit-button: {
      position: relative;
      top: 0;
      left: 0;
    };
    --paper-gui-dialog: {
      position: absolute;
      top: auto;
      right: auto;
      bottom: 0;
      left: 0;
      width: 50%;
    };
  }
</style>

Reference

PaperGUI constructor parameters

The PaperGUI constructor can accept an object containing various options (eg. var gui = new PaperGUI({autoPlace: false});)

Property name	Type	Description
autoPlace	Boolean	Whether to automatically append the PaperGUI element to the DOM as soon as at least one controller has been added. Default is true.

PaperGUI methods

PaperGUI has several methods.

Method name	Description
add()	Creates and returns a new UI controller (controller type varies depending on the arguments, see next section).
el()	Returns the main Element for this PaperGUI (ie a paper-gui component). Useful for attaching it to the DOM manually when autoPlace is disabled.
open()	Opens the dialog containing the controllers. Equivalent to clicking the edit button.
close()	Closes the dialog containing the controllers. Equivalent to clicking the close button in the dialog.
hide()	Hides all PaperGUI elements (edit button, dialog with controllers). Equivalent to pressing the ‘H’ key.
show()	Shows all previously hidden PaperGUI elements.

Controller types

Here’s a summary of the controller types PaperGUI currently supports:

PaperGUI Controller type	Property type	Extra parameters
Button	Function	N/A
Toggle	Boolean	N/A
Text input	String	N/A
Select box	String	[String value] An array of accepted values for the property, required to create a select box instead of a text input)
Slider	Number	Number minValue (optional, default 0), Number maxValue (optional, default 100)
Select box	Number	{String label: Number value} An object whose property names will be used as labels and corresponding values will be set on the property when selected. Required to create a select box instead of a slider.

Controller methods

All controller methods return themselves, allowing to chain method calls. Here is a list of methods.

Method	Description	Controller types
name(labelString)	Defines the label or placeholder text for the controller	All
onChange(callbackFunction)	Calls the function when the value changes	All except Button
min(minNumber)	Sets the minimum authorized value	Slider
max(minNumber)	Sets the maximum authorized value	Slider
step(stepNumber)	Sets the step size	Slider

TODO

• Add live demos
• Add folders/tabs structure capability and other features from the original dat.GUI

Known issues

• Select box change callback fires on controller creation (intended?)