hypeDocument

hypeDocument is the variable name of the Hype API for your document. It is a document specific JavaScript object created while rendering your Hype document and contains the public facing function references from the Hype Runtime know as the Hype API.

Accessing the Hype API through hypeDocument

The first reasn for the existence of the hypeDocument variable is to offer access to functionality provided by the Hype Runtime using JavaScript. This offers advanced ways to implement logic, run animations and change properties of elements in your scenes and layouts. Unfortuanatly the API is in many regards less powerful then the IDE as it only offers access a subset of properties and functions. A full list API functions can be found on the Tumult homepage and in the Hype API. One example to illustrate usage would be a timeline action that only pauses a timeline if triggered while running forward:

// element - DOMHTMLElement that triggered this function being called
// event - event that triggered this function being called
function pauseIfPlayingForward(hypeDocument, element, event) {
	if ( hypeDocument.currentDirectionForTimelineNamed(event.timelineName) == hypeDocument.kDirectionForward) {
		hypeDocument.pauseTimelineNamed(event.timelineName);
	}
}

Adding custom data to your hypeDocument

Any Hype Function has hypeDocument in the function signature and is called with it. So, it becomes convenient to use it for custom data (hypeDocument.customData) and local variables.

For example, you could define the variable hello in customData:

hypeDocument.customData.hello = 'world';

Later, meaning in another Hype function you could use the variable for any task by referencing it through hypeDocument.

if (hypeDocument.customData.hello == 'world'){
  alert('hello world');
}

The benefit is obviously the local nature of your variables and the ease of use managing them in a single location (object).

Adding and modifying hypeDocumet itself

The discussion remaining is around customDataas the previous example also works even when adding your variable to hypeDocument directly:

hypeDocument.hello = world
if (hypeDocument.hello == 'world'){
  alert('hello world');
}

Official recommendation: There is nothing preventing you from doing it and saving yourself some typing but Tumult fears you could be overwriting sanctioned API references or create a namespace conflict in the future. Hence, Tumult added an official predefined object in hypeDocument to reap the benefits of adding local and custom data while keeping people (specially beginner) from the risks and pitfalls.

My personal take on this is the following: The bigger a project becomes clear coding guidelines become important to maintain modularization and clean code. So, I am favoring clear rules in teams and such projects. In many languages coding guidelines are rather a result of best practice and team culture rather than being forced onto the user by syntax requirements. Other languages like Python at least enforce strict indentation as part of the syntax. There is also the conflict between people coming from classical compiler-based languages (like C++, Objective-C or Swift) versus people using interpreter languages (PHP, JavaScript or Python). In the later avoiding strict types and runtime extendability are possible and exploited concepts that are mostly frowned upon by more classical developers. In the world of web development there are many such fields of mixed content and flexible approaches. My conclusion being, that it comes down to understanding name spaces in JavaScript and realizing why customData was added by Tumult. If you are a single developer or are extending hypeDocument with explicitly named new functionality there is low risk of creating conflicts down the line. The worst case is that your assignments overwrites an official on and breaks it for that single instance of hypeDocument as every hypeDocument is its own object. I often use direct assignments in hypeDocument instead of hypeDocument.customData while being aware that it is not best practice as of Hype 4.x.

Fetching hypeDocument from the window scope

outside of Hype IDE, you would need to fetch the Hype API first. Beware that the export name (your choice) differs from the preview name (always index). This becomes relevant when fetching the Hype API as follows:

var hypeDocument = HYPE.documents['index'];

There is a workaround that is name agnostic as it always uses the first found Hype document. That might not be ideal on a page with more than one Hype document and you not being in control of loading order. In cases of a single Hype document or a known loading order this apporach should work:

var hypeDocument = Object.values(HYPE.documents)[0];

Related topics

• There is a helper function called getHypeDocument
• The official API documentation
• The direction pause timlineaction helper used in this article on the forum