Tech Note: Creating External Scenes by Hand

From Waltz
Revision as of 16:22, 27 June 2019 by Patrick Angle (talk | contribs)
Jump to navigation Jump to search

This tutorial assumes an existing understanding of HTML, CSS, and JavaScript and how those technologies interact with each other. For a slightly more user-friendly way to create External Scenes, try Creating External Scenes with Hype.

Scenes in Waltz use standard web technologies, including HTML5, CSS, and JavaScript, to create interactive user experiences inside a standard web browser on both desktop and mobile devices. Waltz contains built-in tools to create scenes, but sometime a greater level of creative control is desired. In these situations an External Scene, built outside of Waltz, can be integrated into Waltz to trigger aspects of your show, as well as display real-time information from Waltz.

Required Dependancies

External Scenes require that your webpage include two script files, which are hosted by Waltz. The files may be updated or change between versions of Waltz, and should not be included by any other method than requesting them from Waltz.

Adding the following two lines to the <head></head> of your HTML document will include the dependancies required to communicate with Waltz.

<script src="/api/jquery.js"></script> 
<script src="/api/waltz.js"></script> 

Waltz requires jquery.js be present in order to function, and it must be included before the waltz.js. You may also provide an up-to-date version of jQuery yourself and omit this import from Waltz.

Initializing Waltz Support

With the two required files loaded, you will have minimal integration with Waltz. Where the integration shines is in the ability to add special classes and data tags to existing elements to perform actions, track values, and display materials from Waltz. For this functionality to work, you need to initialize the Waltz object in JavaScript. This should be done after the page loads and you have created your full DOM. Initializing Waltz support is done with a single call in JavaScript, shown here wrapped in jQuery to wait until the full page has loaded.

$(function() {

The 30 in the example is the number of times per second that information will be updated. While it is normal to run Waltz at 60+ FPS, we generally recommend scenes run at about 30 FPS.

Performing Actions in Waltz

Actions are similar to Scripts in Waltz. They are able to interact with any node or nodes on the stage, and the output of the script does not matter. The script is execute every time an element is clicked/tapped or when any event as defined below has occurred.

Any element in the DOM that supports JavaScript events can execute an action on click/tap, or if desired on a specially assigned event for that element.

Waltz integration uses Classes to describe available functionality on an element. To perform an action, first add the waltzAction class to the element. Then add a custom data attribute named data-waltz-action to the element with the script you wish to be executed by Waltz as its value. For example, a button can be configured to send an OSC message using a node named oscOutput from our show with the follow snippet of HTML. <button class="waltzAction" data-waltz-action="$.oscOutput.send()">Do the cool thing!</button> When you call Waltz.init(30), this will automatically be converted into a button that can communicate with Waltz for you, without having to define additional action handlers.

If you want, for example, the action to only be performed when the mouse stops hovering over the element, you can add a data-waltz-action-event attribute with a value of mouseleave to the button, and Waltz will attach the action to the specified event instead of the default (which varies depending on whether a touch-screen is present). The HTML for the same button would then look like: <button class="waltzAction" data-waltz-action="$.oscOutput.send()" data-waltz-action-event="mouseleave">Do the cool thing!</button>

Displaying Values from Waltz

Displaying values from Waltz is just as simple as performing actions, and works mostly in the same. The contents of the configured element will be emptied and replaced with the value from Waltz, so it is generally best to use a small element, like a span, to contain only the data from Waltz. To make an element contain a value from Waltz, it must have waltzValue added to its classes, and have a data-waltz-value attribute with an expression from which the value will come. In the example below, the value of a Wave node, conveniently called wave, is displayed with a title preceding it.

<p>My great wave number is: <span class="waltzValue" data-waltz-value="$.wave.output"></span></p>

In this example, notice how we apply the Waltz-specific properties only to the inner span element, not the full paragraph. If we applied the properties to the paragraph, our title before the number would not be visible.

Showing Materials from Waltz

The final supported integration with Waltz is the displaying of materials on the web page. On web pages, materials are backed by canvas elements, but Waltz will handle this implementation detail for you. In generally, you will use a div element with a class of waltzMaterial and a data-waltz-material attribute with an expression referring to a material in Waltz. For example, to show a 300x200 pixel graph from a node named graph, you would write…

<div style="width: 300; height: 200;" class="waltzMaterial" data-waltz-material="$.graph.material"></div>

Notice that in order to make the div the correct size for our specific material, we define the width and height. A material should be scaled before being broadcast over the network if a different size is needed.