hypeDocument.customData quick examples of setting and getting data

Tips & Tricks
1

Here are some examples of setting the new hypeDocument.customData API

The API is initially an empty object {} it is also global within the scope of your Hype project.

An Object {} can hold many types of data. Strings “”, Arrays [], Numbers and the Objects {}.

But each item of data is classed as the Value.

A value Must have a key . the key is the name that you can use to retrieve the value.

( This is different to an Array. In an Array you can only retrieve an item by it’s index which is it’s place in the array of items. )

So the hypeDocument.customData is a key/value object.

An example of a key/value object syntax would be;

{“foo”:“some foo fun”, “foo2”: 2}

Above we have the key foo with a string value of some foo fun and the key foo2 with a number value of 2

The value is placed after key and a colon " : "

We can add a new object to the hypeDocument.customData like so;

hypeDocument.customData["some_Text"] = "Some Text string"

Here we are saying ; hypeDocument.customData add the key some_Text and set it’s value to Some Text string

In the above example we use a string to construct the key so it must be surrounded by the [] brackets.

We could say the same thing like this;

hypeDocument.customData.some_Text = "Some Text string"

The brackets are also a useful construction method for when we want to use a var as a key name.

like this

 var someKey = "yoyo" 

 hypeDocument.customData[someKey] = "Some Text string 2"

Retrieving the above:

We can use similar construction to retrieve object values

We use the key.

hypeDocument.customData.some_Text --> "Some Text string"
hypeDocument.customData["some_Text"] --> "Some Text string"

hypeDocument.customData.yoyo --> "Some Text string 2"
hypeDocument.customData["yoyo"] --> "Some Text string 2"

More examples .

An Array of Strings
hypeDocument.customData["text_Array"] = ["lol","imho","wtf"]

hypeDocument.customData["element_Array"][0] --> returned the first item (index 0 ) in the the array

An Array of Elements
hypeDocument.customData.element_Array = document.querySelectorAll('.test')

hypeDocument.customData. element_Array[0] --> returned the item (index 0 ) in the the arrayhypeDocument.customData. element_Array[3] --> returned the 4th item (index 3 ) in the the array`

An Object with key/values
hypeDocument.customData[“text_object”] = {“lol” : “laugh out loud”,“imho”: “In my Honest Opinion”,“wtf”: “You know what this is…”}

hypeDocument.customData.text_object.wtf --> "You know what this is.."

Note here we access the key text_object in hypeDocument.customData and the key wtf form the returned value which is an object itself.

This is not the be all and end all of Objects there is much more that can be done but I hope it helps get you started with testing and using it.

–

11 Likes
2

Thanks for the thorough docs @MarkHunte! We’ll have to make sure this gets out of the Hype Beta category once v4 is released.

2 Likes
3

customData is currently missing from the documentation, but this is a great example of how to use it.

4

Thank You Mark! Honking%20Horn%20right

1 Like
5

It would be very helpful to know more especially what are the relative merits of customData vs. regular javascript calls to localStorage.

6

It’s currently just a place to pass around data from scene to scene and specially Hype function to Hype function as the API for the current Hype document is held in it’s parent hypeDocument passed into every Hype function (see signature of the Hype functions).

In it’s current form in the API it’s actually only a plain Object. But it’s mighty convenient as it is local to your Hype document and with it’s “mount point” in hypeDocument omnipresent to local Hype functions in your current document.

That said there is nothing stopping you from creating hypeDocument.myCustomData={}; but introducing an official mount point helps to unify the places we start mounting such things. Also if the day comes the API locks down full write access to it’s API Object hypeDocument (hope that never happens) it would offer an official place to add data.

For persistence on customData with some added benefits have a look at Hype StorageKit. If you want to write something yourself just use localStorage on the customData object as that isn’t persistent in it’s current form nor does it intend to be.

2 Likes