Tech Note: Creating External Scenes by Hand
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.
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
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.
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.