How to add your own data handler - worldoptimizer/HypeDataMagic GitHub Wiki

Preparation

First off it is important to know that Hype (intentionally) breaks complex JavaScript you add in your Head HTML as long as you're in the IDE. As we want to enjoy live previews for our additional or custom data handlers the best approach is to add them into an external source file. This is done by creating a file like AdditionalHandler.js with your favorite text editor and then dragging it into the resource library. This will automatically link it into your HeadHTML. As we want it to link after loading HypeDataMagic.min.js make sure the order is set accordingly. If not an easy hint is to copy & paste the script code of your AdditionalHandler.js Hype included in Head HTML, then disable the "include in document <head>" option and paste it in manually. It should look something like the following screenshot once you are done.

CleanShot 2020-10-03 at 01.08.13@2x

As you can see the order is firstHypeDataMagic.min.js①  (from the CDN) and then secondlyAdditionalHandler.js② (from our resources folder)

Here is the code section if you want to copy & paste it. Please adjust AdditionalHandler.js to match your filename.

<script src="https://cdn.jsdelivr.net/gh/worldoptimizer/HypeDataMagic/HypeDataMagic.min.js"></script>
<script type="text/javascript" src="${resourcesFolderName}/AdditionalHandler.js"></script>

Hype Templates

You can download a template to add your handler or just to look at the setup as a blue print to get you started.

Adding handler to the head section:

HypeDataMagic-AddHandler-Head.hypetemplate.zip

Adding handler to an external file:

HypeDataMagic-AddHandler-Resources.hypetemplate.zip

Events in data handler

You can extend Hype Data Magic by adding additional handlers. The handlers have to be defined along the Hype Events and are named pretty similiar. These are the events that are coverd by Hype Data Magic:

Name Discription
DataMagicPrepareForDisplay This event is the default event and is fired the moment the element is prepared for display along the regular HypePrepareForDisplay
DataMagicLoad This event is fired when the scene loads and is the perfect place to launch timelines or do anything you would traditionally do in HypeSceneLoad
DataMagicUnload This event is fired along HypeSceneUnload but if defined also when a data handler is refreshed or updated in the IDE to clean up after itself. If you don't define this handler it defaults to resetting the innerHTML to an empty string.

Apart of these two events there is a special event:

Name Discription
DataMagicPreviewUpdate This event is fired on updates in the IDE. If the event isn't explicitly defined when setting up the data handler it defaults to DataMagicPrepareForDisplay.

Syntax to define a data handler

Simple definition

This is done as a direct function handler (good for simple formatting)

HypeDataMagic.addDataHandler('NAME', function (hypeDocument, element, event){
  // your code here
});

Here is a simple handler to window dress number using German euro currency notation

HypeDataMagic.addDataHandler('euro', function(hypeDocument, element, event){
	if (event.data) {
		if (element.innerHTML != event.data) {
			element.innerHTML = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(event.data);  
		}
	}
});

More advanced handler declaration

This is defined as an object with the event names as keys

HypeDataMagic.addDataHandler('NAME', {
	DataMagicPrepareForDisplay: function (hypeDocument, element, event){
		// your code here
	},
	DataMagicLoad: function (hypeDocument, element, event){
		// your code here
	},
	DataMagicUnload: function (hypeDocument, element, event){
		// your code here
	}, 
	DataMagicPreviewUpdate: function (hypeDocument, element, event){
		// your code here
	},  
});

Here is a handler example using a subset of these callbacks to implement a fictional background color based on data called positive:

HypeDataMagic.addDataHandler('positive', {
	DataMagicPrepareForDisplay: function (hypeDocument, element, event){
			if (!element.getAttribute('data-original-background-color')){
				element.setAttribute('data-original-background-color', element.style.getPropertyValue('background-color'));
			}
			if (event.data >= 0) { 
				element.style.setProperty('background-color', 'green', 'important');
			} else {
				element.style.setProperty('background-color', 'red', 'important');
			}
	},
	DataMagicUnload: function (hypeDocument, element, event){
		if (element.getAttribute('data-original-background-color')){
			element.style.setProperty('background-color', element.getAttribute('data-original-background-color'));
			element.style.removeAttribute('data-original-background-color');
		} else {
			element.style.removeProperty('background-color');
		}
	}
});

Further reads:

  • Choose another topic from the sidebar
  • Return to the welcome page
  • Consider making an one-time donation

Sponsorship:

Become a sponsor of this project!

⚠️ **GitHub.com Fallback** ⚠️