Hype Symbol Cache

[MaxZieb (Loves Hype)]

This is a quick release of a nerdy extension to solve the inconsistent Symbol-API provided by the runtime. Background being that the runtime applies initial values including a fresh copy of the Symbol API multiple times including when HypeSceneLoad, HypePrepareSceneForDisplay and HypeDocumentLoad runs. Meaning the runtime makes it hard on using the Symbol API consistently to store Symbol specific values like possible with hypeDocument. The symbol API stays constant in a scene but you have to redefine any additions on each “On Scene Load” or HypeSceneLoad. You can’t store a symbol specific counter or anything across scenes in the Symbol API.

This extension caches the Symbol API and always returns the first cached version. This way you can rely on it being stable and cached. Hence, the name. It also gives you a new callback “HypeSymbolInit” fired when a symbol is cached (so only fired once).

Documentation

There is a JSDoc based documentation of the functions at

Hype SymbolCache

Code repository on GitHub

worldoptimizer/HypeHandlebars

Version-History:

1.0 Initial release under MIT-license
1.1 Bugfixes, additional API and immediate refresh

Content Delivery Network (CDN)

Latest version can be linked into your project using the following in the head section of your project:

<script src="https://cdn.jsdelivr.net/gh/worldoptimizer/HypeSymbolCache/HypeSymbolCache.min.js"></script>

Optionally you can also link a SRI version or specific releases.
Read more about that on the JsDelivr (CDN) page for this extension at https://www.jsdelivr.com/package/gh/worldoptimizer/HypeSymbolCache

Learn how to use the latest extension version and how to combine extensions into one file at

worldoptimizer/HypeCookBook

Read the article about the extension on Medium

Extending Tumult Hype Symbols (using Hype Symbol Cache)

[MaxZieb (Loves Hype)]

This is how you can use the new event. But that is optional the extension also works with the regular and built in events and symbol API calls.

function symbolInitTest (hypeDocument, element, event){
		console.log('HypeSymbolInit');
		var symbolInstance = hypeDocument.getSymbolInstanceForElement(element);
		// do your stuff…
	}
	
	window.HYPE_eventListeners.push({"type":"HypeSymbolInit", "callback":symbolInitTest});

[h_classen (Hans-Gerd Claßen)]

could you eleborate on usecases? I’m confused …

[MaxZieb (Loves Hype)]

Simply put, you can store values and extensions in symbols. Basically, it allows adding methods to symbols while also keeping a “State” in individual symbols. Each symbol instance is an object much like hypeDocument and can also be “extended” tweaked and used for storage. In Hype you can already “out of the box” do this but the runtime resets any state (or extension) as every scene and document event “destroys” the symbol instance by fetching a new object describing it. If you only use On Scene Load to setup and the single scene context is enough for you, you can already do some stuff as is. But, you will hit a wall when trying to add methods in Document Load as they are reseted when switching to the subsequent scene (or moving from scene to scene). The same goes for state data of symbol instances you might want to retain across scenes.

I admit it’s a special case extension but there are use cases … specially when thinking about state driven component-based approaches using symbols.

This extension makes every symbol instance object “stable” or persistent… but I refrained from calling it persistent symbol instance to avoid confusion with persistent symbols as we are only talking about the symbol instance (object) being stable.
If you need a scene change to destroy/reset symbol instance objects (like it’s the default in regular Hype) you can call the method hypeDocument.purgeSymbolCache(). You can also purge the symbol cache for individual symbol instances using the element ID of the symbol with hypeDocument.purgeSymbolCacheForId(YOUR-ID);. Once a symbol is purged it will re-init on the next symbol load or when you fetch it again with the API. Speaking of it I might add a switch (Boolean) on the purge functions to re-init immediately.

[h_classen (Hans-Gerd Claßen)]

thx

so far i’ve never extended the SymbolInstanceObject … so never discovered the reset Hype does. Nice new feature

[MaxZieb (Loves Hype)]

What would you name this extension?

• Stable Symbol
• Persistent Instances

[h_classen (Hans-Gerd Claßen)]

The word instance suggests some js-object. where as symbol is also important, cause the subject is around symbols. what about: Stable Symbols Instances?

[MarkHunte]

I presantly storing states in a global. i.e
each instance of a symbol has it’s own state saved, when the scene changes these are read back in.
I also have used this to direct a function run to which instance uses it.

Is this what you are meaning to help with… ?

[MaxZieb (Loves Hype)]

↑ look at project
1.1 Bugfixes, additional API and immediate refresh

[MaxZieb (Loves Hype)]

Here is a simple example to illustrate the usage. This file has the extension included from the JsDelivr CDN (head over to the GitHub-Repository for further instructions and a minified version)

This is only one use case and the way I am using the init and load with Object.assign has nothing to-do with the extension. This could be extended and used in many ways. It’s just one example and way of doing it given a symbol instance is extended (counter). This is just to make the point and by no means a template or so…

function symbolInit (hypeDocument, element, event){
	console.log('HypeSymbolInit');
	var symbolInstance = hypeDocument.getSymbolInstanceForElement(element);
	var symbolElement = symbolInstance.element();
	switch (symbolInstance.symbolName()){
		case 'counter':
			Object.assign( symbolInstance, {

				_counter: 0,
				
				increase: function(){
					this._counter++;
					this.refresh();
				},
				
				decrease: function(){
					this._counter--;
					this.refresh();
				},
			
				getValue: function(){
					return this._counter;
				},

				refresh: function(){
					symbolElement.querySelector('.display').innerHTML = this._counter;
				},
				
			});
				
			symbolElement.querySelector('.upBtn').onclick = function(){
				symbolInstance.increase();
			}
			
			symbolElement.querySelector('.downBtn').onclick = function(){
				symbolInstance.decrease();
			}
			
			symbolInstance.refresh();
			break;
	}
}

function symbolLoad (hypeDocument, element, event){
	var symbolInstance = hypeDocument.getSymbolInstanceForElement(element);
	switch (symbolInstance.symbolName()){
		case 'counter':
			symbolInstance.refresh();
			break;
	}
}


window.HYPE_eventListeners.push({"type":"HypeSymbolInit", "callback":symbolInit});
window.HYPE_eventListeners.push({"type":"HypeSymbolLoad", "callback":symbolLoad});

Download:
HypeSymbolCache.hype.zip (57,5 KB)

Preview:
HypeSymbolCache.html

[MaxZieb (Loves Hype)]

↑ look at project
Added a JSDoc based documentation of the functions

Hype SymbolCache