This is documentation for Tumult Hype 2.5.3, released in October of 2014.

View Latest Documentation

Tumult Hype Documentation — JavaScript

Using JavaScript

Creating a new JavaScript

JavaScript functions within Tumult Hype are generally run in response to user events. In any action panel, such as the panels found in the Mouse Actions inspector, create a JavaScript function by following these steps:

  1. Click the Plus button in the action’s header to add a new action.
  2. Click the Action menu and choose Run JavaScript… .
  3. Click the Function menu and choose New Function… .

This will open a new JavaScript Editor tab where custom JavaScript functions can be written. A sample JavaScript function looks like the following:

 function untitledFunction(hypeDocument, element, event) {
  alert('Hello World');
 }

You can edit the name of the function by editing the “untitledFunction” portion of the code or by editing the name in the Resource Library. JavaScript function names must not start with a number. Function code can only be inserted between the curly brackets. The portion (hypeDocument, element, event) is required and therefore not editable.

JavaScript Documentation Viewer

The Documentation Viewer below the editing area can be helpful for quickly building JavaScript functions based on API functions. Tumult Hype’s Documentation Viewer provides in-app documentation for all of Tumult Hype’s JavaScript API functions, and also allows functions to be quickly inserted into the JavaScript editor. To insert any function:

  1. Place the editor’s cursor where you want the function to be inserted.
  2. Select the JavaScript function you wish to be inserted.
  3. Click the Insert button () to the right of the function name.

Functions can also be inserted by dragging-and-dropping them from the functions listing or by double-clicking their row.

API Functions

Tumult Hype offers many JavaScript APIs to control various aspects of a document. These APIs can be called both by JavaScript functions written within Tumult Hype, and by scripts external to the document.

Document

hypeDocument.documentName()

Returns the name of the document. This value can be used in the global HYPE.documents[documentName].

hypeDocument.documentId()

Returns the id of the container div for the document. This value can be used with document.getElementId() to retrieve the container element itself.

hypeDocument.resourcesFolderURL()

Returns the string value for the the document’s resources folder URL. Use this to reference assets added via the Resource Library.

hypeDocument.functions()

Returns an array of all user-defined JavaScript functions in the Tumult Hype Document.

hypeDocument.getElementById(id)

Searches the current document for the specified id (entered through the Identity inspector’s “Unique Element ID”) and returns the DOM HTML Element. This is similar to the typical document.getElementById, however the API version should be used instead as Tumult Hype may reassign ids in cases of collision.

hypeDocument.relayoutIfNecessary()

Explicitly tells the document to relayout all elements and groups for the current scene when using a flexible layout. Use if you have externally changed the bounding size of the main container.

Scenes

hypeDocument.sceneNames()

Returns a list of all scenes in the document.

hypeDocument.currentSceneName()

Returns the string value for the currently shown scene.

hypeDocument.showSceneNamed(sceneName, optionalTransition, optionalDuration)

Changes to the specified scene. If the optionalTransition is not specified it will default to the instant transition. See below for a list of valid transition constants.

The optionalDuration parameter is given in seconds; the default value is 1.1.

Note: Scene names are user-defined and uniqueness is not enforced. If you are going to use this function, be sure that no two scenes in any document have the same name.

hypeDocument.showNextScene(optionalTransition)

Shows the next scene, based on the order in the scene selector interface. If the optionalTransition is not specified it will default to the instant transition. See below for a list of valid transition constants.

hypeDocument.showPreviousScene(optionalTransition)

Shows the previous scene, based on the order in the scene selector interface. If the optionalTransition is not specified it will default to the instant transition. See below for a list of valid transition constants.

Timelines

hypeDocument.startTimelineNamed('timelineName', direction)

Starts the specified timeline at the beginning for the current scene. Note: timelines are user-defined, so they are not enforced to be unique. If you are going to use this function, be sure that no two timelines in any scene have the same name!

Direction to play timeline:

hypeDocument.kDirectionForward
hypeDocument.kDirectionReverse

Note: this function was named hypeDocument.playTimelineNamed(timelineName) in Tumult Hype 1.5 and earlier.

hypeDocument.pauseTimelineNamed('timelineName')

Pauses the specified timeline for the current scene.

hypeDocument.continueTimelineNamed('timelineName', direction)

Continues the specified timeline in the direction specified where it left off for the current scene. Note: timelines are user-defined, so they are not enforced to be unique. If you are going to use this function, be sure that no two timelines in any scene have the same name!

Direction to play timeline:

hypeDocument.kDirectionForward
hypeDocument.kDirectionReverse

hypeDocument.goToTimeInTimelineNamed(timeInSeconds, 'timelineName')

Jumps to a specific time in the specified timeline for the current scene.

hypeDocument.currentTimeInTimelineNamed('timelineName')

Returns the current time of the specified timeline in seconds.

hypeDocument.durationForTimelineNamed('timelineName')

Returns the duration of the specified timeline in seconds.

hypeDocument.currentDirectionForTimelineNamed('timelineName')

Returns the playback direction of the specified timeline.

Possible return values:

hypeDocument.kDirectionForward
hypeDocument.kDirectionReverse

hypeDocument.isPlayingTimelineNamed('timelineName')

Returns true if the timeline is playing and false if it is not.

Note: Timeline names are user-defined and uniqueness is not enforced. If you are going to use these functions, be sure that no two timelines in any scene have the same name.

Dragging

JavaScript functions invoked by the On Drag handler can gather information about the current drag gesture.

event['hypeGesturePhase']

When receiving a callback for the On Drag event with the Run Javascript… action the event object also offers information about whether the current drag gesture has just started or ended, was canceled, or the coordinates were updated. To get that state, access the hypeGesturePhase property in the event object:

  hypeDocument.kHypeGesturePhaseStart
  hypeDocument.kHypeGesturePhaseMove
  hypeDocument.kHypeGesturePhaseEnd
  hypeDocument.kHypeGesturePhaseCancel

event['hypeGestureXPosition']

Returns the current x position of a drag when using the "On Drag" event with the "Run Javascript…" action.

event['hypeGestureYPosition']

Returns the current y position of a drag when using the "On Drag" event with the "Run Javascript…" action.

API Constants

The only constants exposed are those for scene transitions:

hypeDocument.kSceneTransitionInstant
hypeDocument.kSceneTransitionCrossfade
hypeDocument.kSceneTransitionSwap
hypeDocument.kSceneTransitionPushLeftToRight
hypeDocument.kSceneTransitionPushRightToLeft
hypeDocument.kSceneTransitionPushBottomToTop
hypeDocument.kSceneTransitionPushTopToBottom

Examples

To show a scene named “Yellow” with the Instant transition style, this API function call would be used:

hypeDocument.showSceneNamed('Yellow');

To show a specific scene named “Blue” from the JavaScript editor, using a Push Right to Left transition, and then play a timeline named “Robin” these function calls would be used:

hypeDocument.showSceneNamed('Blue', kSceneTransitionPushRightToLeft);
hypeDocument.playTimelineNamed('Robin');

Invoking API from outside of Tumult Hype

To access the Tumult Hype API from a JavaScript outside of the embedded document, you can use the global Tumult Hype object:

HYPE.documents[documentName]

The document may not be an exact match for the filename. To figure out the value, you can look inside the exported Resources folder for the *_hype_generated_script.js file and find the document’s name there. You can also call the hypeDocument.documentName() function from within a JavaScript action to determine it.

Events

To help external JavaScripts integrate and interact with embedded documents Tumult Hype offers an event callback system, allowing external JavaScript functions to be triggered in response to events in embedded documents. One purpose for an externally invoked event would be to jump between scenes using controls outside of your Tumult Hype document for a slideshow. At this time, four event callbacks are offered, so functions can be registered for document loading, scene loading and unloading, and timeline completion:

HypeDocumentLoad
HypeSceneLoad
HypeSceneUnload
HypeTimelineComplete

The HypeTimelineComplete event also adds a name property to the event object, so you can determine which timeline raised the event.

Examples

The following example registers an event to be run after the HypeDocumentLoad event has occured.

 <script>

  function myCallback(hypeDocument, element, event) {
    // display the name of the Hype container and the event called
    alert("id: " + element.id + " type: " + event.type);

    // show the scene named SecondScene
    hypeDocument.showSceneNamed('SecondScene');

    // return false so it does not load the initial scene
    return false;
  }

  if("HYPE_eventListeners" in window === false) {
    window.HYPE_eventListeners = Array();
  }
  window.HYPE_eventListeners.push({"type":"HypeDocumentLoad", "callback":myCallback});

 </script>

The following line in the above JavaScript receives the HypeDocumentLoad event callback:

window.HYPE_eventListeners.push({"type" : "HypeDocumentLoad", "callback" : myCallback});

In the above code, HypeDocumentLoad is the event for which the callback should be triggered, and myCallback is the JavaScript function which should be invoked by the event. This JavaScript can be invoked outside of Tumult Hype, and can potentially be placed within the <head>…</head> of the exported .html file generated by Tumult Hype by clicking on 'Edit HTML Head' in the Document Inspector. To see this function in action, download this example file. When previewed in a browser, the code in the document's head will load the second scene and an additional timeline on that scene.

To control the document above, use these buttons:

| |

These buttons make use of Tumult Hype’s JavaScript API constants. The full code for the Push Right to Left button is:

 <button type="button" onclick = "HYPE.documents['scenes-transitions'].showSceneNamed('Scene2',HYPE.documents['scenes-transitions'].kSceneTransitionPushRightToLeft);">
   Show Scene 2 (Push Right to Left)
 </button>

Switch to a scene named Red from a document named HypeExample using the Push Right to Left transition:

 <a href = "#" onclick = "HYPE.documents['HypeExample'].showSceneNamed('Red',HYPE.documents['HypeExample'].kSceneTransitionPushRightToLeft);">Go to Red</a> 

Switch to the next scene in a document named HypeExample using the Crossfade transition:

 <a href = "#" onclick = "HYPE.documents['HypeExample'].showNextScene(HYPE.documents['HypeExample'].hypeDocument.kSceneTransitionCrossfade);">Crossfade to next scene</a>

Note: Because the HYPE global variable may not be available immediately after HTML document has been loaded, this is the only reliable way to trigger external JavaScript functions in response to an embedded Tumult Hype document being loaded.

Additional questions?

If you have any additional questions not covered here, please visit the JavaScript support forum or ask us a question.