Link Search Menu Expand Document
Gorilla Engine
Table of contents

Dynamic Controls Example

Dynamic Controls Example

This example can be found in the Examples folder of the Gorilla Engine SDK. It shows how a simple mouse click can add or remove a control from the UI.

If you have explored Gorilla Engine UI examples, you may already know that there is a convenient YAML declaration file that lets you add new controls to the UI with just a few lines of code. When adding such controls, you must add those lines before you compile your plugin in the Gorilla Compiler. This is fine for most static UIs that are known and do not change. However, this method does not work if you have dynamic controls such as web requests where the UI element may not be known.

For example, imagine you want to request a list of effect presets from the cloud and display them to the user. In this case, you may not know exactly how many presets will be returned in the response to your request. As a result, you’ll need to create a list that is dynamic.

This example introduces:

  • How to access static controls declared in the YAML from JavaScript
  • How to use JavaScript to add and remove controls to the UI at runtime

Dynamic Controls - JavaScript

Note: The following is not intended as a step-by-step guide on how to use JavaScript and YAML (we provide an Intro to UI Development and a JavaScript reference). The idea here is to introduce you to the possibility of dynamically adding and removing controls during runtime. This gives you some creative freedom when designing your product.

The following JavaScript code is identical to the .js file found in the plugin_assets folder of the Dynamic Controls example.

/*jshint esversion: 6 */
const path = require("path");

const blobPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}_part1.blob`
);
const blob = GorillaEngine.loadBlob(blobPath);
const instrument = blob.loadInstrument(blob.getInstrumentNames()[0]);
GorillaEngine.setActiveInstrument(instrument)

const yamlPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}.yaml`
);
GorillaEngine.UI.loadUIfromYAML(yamlPath);

const label = GorillaEngine.UI.getControlById("myLabel");
const trigger = GorillaEngine.UI.getControlById("myTrigger");

trigger.on("click", (modifier) => {
  if (label.children.length === 1) {
    const triggerToAdd = new GorillaEngine.UI.Trigger({
      id: "secondTrigger",
      x: 10,
      y: 100,
      width: 380,
      height: 90,
      text: "Press this and remove the button",
    });

    triggerToAdd.on("click", (modifier) => {
      label.removeChild(triggerToAdd);
    });

    label.appendChild(triggerToAdd);
  }
});

Let’s take a closer look.

Loading a blob file

Most Gorilla Engine based products are based on blob that are exported by Gorilla Editor. If you are not aware of how to create blob files, take a look at our Gorilla Editor documentation.

const blobPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}_part1.blob`
);
const blob = GorillaEngine.loadBlob(blobPath);
const instrument = blob.loadInstrument(blob.getInstrumentNames()[0]);

Loading YAML UI declaration from JavaScript

UI parts that are “static” (e.g., known at compile time) can be declared in a yml file and can then be loaded in one go by calling GorillaEngine.UI.loadUIfromYAML passing it the path to the yml file.

const yamlPath = path.join(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}.yaml`
);
GorillaEngine.UI.loadUIfromYAML(yamlPath);

Adding and removing a trigger at runtime

This piece of JavaScript code finds the label in the UI that we already created statically through the yml declaration and appends a new Trigger control to it.

// find the label that we want to append the new trigger to
const label = GorillaEngine.UI.getControlById("myLabel");

// find the trigger that appends the new trigger when clicked
const trigger = GorillaEngine.UI.getControlById("myTrigger");

// add a click handler to the already existing trigger
trigger.on("click", (modifier) => {
  // if we didnt append the new trigger already, append it
  if (label.children.length === 1) {
    // define the new trigger
    const triggerToAdd = new GorillaEngine.UI.Trigger({
      id: "secondTrigger",
      x: 10,
      y: 100,
      width: 380,
      height: 90,
      text: "Press this and remove the button",
    });
    // add a click handler to the new trigger
    triggerToAdd.on("click", (modifier) => {
      // removes itself
      label.removeChild(triggerToAdd);
    });

    // actually append the new trigger to the label that we found earlier
    label.appendChild(triggerToAdd);
  }
});

Implementing a trigger using YAML

The following YAML code is very basic and parts of it can be applied to almost any Gorilla Engine based plugin. If you want to click a button, you will always need a trigger to perform the desired action, regardless of the individual product.

Most of the used properties will hopefully be self-explanatory, however, if you would like an overview of all available UI controls and their properties, take a look at our Gorilla Engine - JavaScript API Reference.

window:
  width: 400
  height: 300
  background_color: 49494e
  children:
    - label:
      id: myLabel
      x: 0
      y: 0
      width: 400
      height: 300
      children:
        - trigger:
          id: myTrigger
          x: 10
          y: 10
          width: 380
          height: 90
          text: Press this trigger and JS will add a second trigger control at runtime