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 reason for the existence of the hypeDocument variable is to offer access to functionality provided by the Hype Runtime using JavaScript. These offers advanced ways to implement logic, run animations and change properties of elements in your scenes and layouts. Unfortunately the API is in many regards less powerful than 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.

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).

Modifying hypeDocument directly

If you are asking yourself why there is a customData and what happens if you add your variables directly to hypeDocument you are rightfully asking such questions. The previous example would also works when adding your variable directly to hypeDocument as hypeDocument is nothing more than an JavaScript object. Here is the same example spelled out without using the customData object:

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

This leads to a discussion on what, why and when to follow or break convention. First let us examine the official recommendation and then I'll add my personal take to it.

Official recommendation: There is nothing preventing you from modifying hypeDocument (nor should there be) 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 latter 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 approach 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