dat.gui Minimal Example

Posted on 11 Jun 2016

dat.gui is a small js library to create a widget in the upper right corner of the screen, with which variables can be changed (see examples).

I love how simple this widget is: You specify the variables you want to influence, and based on the each variable type, dat.gui will automatically add the appropriate UI element:

string –> edit field
function –> checkbox
number –> slider (use optional arguments to restrict range)

This is a minimal HTML example on how to use it in a small app with only one variable (see result here):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset=utf-8 />
    <style type="text/css">
      /* style goes here */
    </style>
    <title>dat.gui Test</title>
  </head>
  <body>
    <h1>dat.gui Test</h1>
    <script type="text/javascript" src="dat.gui.min.js"></script>
    <script type="text/javascript">
var MainView = function() {
  this.message = 'hello there';
  this.appContainer = document.createElement('div');
  this.appContainer.innerHTML = this.message;
  document.body.appendChild(this.appContainer);
};

var mainView = new MainView();
var gui = new dat.GUI();
gui.add(mainView, 'message').onFinishChange(function (newText) {
  mainView.appContainer.innerHTML = newText;
});
    </script>
  </body>
</html>

Some small comments, since I have not used JavaScript in ages:

The "main GUI" is defined as a MainView object, which is created with var mainView = new MainView();

The constructor MainView() has lots of internals defined with via the this keyword. This makes these properties accessible to the public, so that dat.gui can see them. It also ensures that they can be changed by other callbacks, etc. It's always a bit confusing what this actually refers to, but since we only create one of these objects, we are pretty much fine either way.

The scripts are placed at the bottom of the body tag (old school) to ensure that document.body exists. Some people view this as bad style, since then the JS is loaded last, but in this case that's OK, since nothing else is deferring loading of the app.

The gui.add(...) defines the meat of the GUI widget. This line includes a callback for what to do when the user entered a new value. Having to define the callbacks like this makes the definition of the widget less clear than often shown in examples. In the online examples, they cheat by shoving the callbacks into the MainView() object (see example here and inspect the source). This is shown in the modified example below. It does make the definition of the GUI look prettier, but I don't like it, because:

The type of callback seems to be limited to onChange, as opposed to something like "onFinishedChange". Typically, I don't want that.
It uses more lines of code.
message is a pseudo-object that also exists as argument of the creator. That's pretty advanced stuff, where scope and this becomes confusing. No thank you - I'd rather stick to the simpler code that is easier to reason about.

In any case, here is the code of the modified example (see result here, should look identical to first example):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset=utf-8 />
    <style type="text/css">
      /* style goes here */
    </style>
    <title>dat.gui Test</title>
  </head>
  <body>
    <h1>dat.gui Test running</h1>
    <script type="text/javascript" src="dat.gui.min.js"></script>
    <script type="text/javascript">
var MainView = function(message) {
  // __defineGetter__ and __defineSetter__ makes JavaScript believe that
  // we've defined a variable 'this.message'. This way, whenever we
  // change the message variable, we can call some more functions.
  this.__defineGetter__('message', function() {
    return message
  });
  this.__defineSetter__('message', function(m) {
    message = m;
    this.changeMessage(m)
  });
  
  this.appContainer = document.createElement('div');
  this.appContainer.innerHTML = message;
  document.body.appendChild(this.appContainer);
  
  this.changeMessage = function(m) {
    this.appContainer.innerHTML = m;
  };
};

var mainView = new MainView('hello again');
var gui = new dat.GUI();
gui.add(mainView, 'message');
    </script>
  </body>
</html>

I came across the dat.gui library while looking at the awesome experiment Texter.