Back to Top

Hype DataMagic master

Allows you to easily add and handle data in your Hype documents (with live preview)

_default()

defaults can be overriden with setDefault

Properties

Name Type Description
source string
  • the default source of the data
fallbackImage function
  • fallback image if no image is provided (defaults to empty PNG)
handler string
  • default handler if not provided using data-magic-handler
variables object
  • default variables (used instead of custom Data if set)
handlerMixin object
  • handler mixins
sourceRedirect object
  • the source redirect lookup
refreshOnSetData boolean
  • trigger refresh on set data
refreshOnCustomData boolean
  • trigger refresh on custom data
forceRedrawElement boolean
  • force redraw elements
forceRedrawDocument boolean
  • force redraw document
allowDataFunctions boolean
  • allow data functions
allowVariables boolean
  • allow variables
allowDatasets boolean
  • allow datasets
resourcesFolderNameForPreview string
  • the resources folder name for previews (is usually autodetected)

Returns

Void

forceRedraw(element)

Force redraw of an element

Parameters

Name Type Description
element HTMLElement

Returns

Void

callHandler(hypeDocument, element, event)

Calls the handler function for the given event. This function is called by the event handler. It calls the handler function for the given event.

Parameters

Name Type Description
hypeDocument HYPE.documents.HYPEDocument

The document object.

element HTMLElement

The element that triggered the event.

event Object

The event object.

Returns

Void

updateMagicKey(hypeDocument, element, event)

This function is used to update the magic key of an element.

Parameters

Name Type Description
hypeDocument object
  • The hypeDocument object.
element object
  • The element object.
event object
  • The event object.

Returns

Void

unloadMagicKey(hypeDocument, element, event)

This is a description of the unloadMagicKey function.

Parameters

Name Type Description
hypeDocument HypeDocument
  • The HypeDocument object.
element HTMLElement
  • The element that triggered the event.
event Event
  • The event object.

Returns

hasNoHypeElementsAsChild(element)

This function checks if the element has no Hype elements as child.

Parameters

Name Type Description
element HTMLElement
  • The element to check.

Returns

boolean

  • True if the element has no Hype elements as child, false otherwise.

createChangeObserver(hypeDocument, baseContainer)

The change observer is a MutationObserver that observes the DOM for changes to the data-magic-* attributes. When a change is detected, the change observer will call the appropriate functions to update the magic key. This function creates a change observer for the specified Hype document.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.
baseContainer HTMLElement
  • The base container.

Returns

Void

enableChangeObserver(hypeDocument)

Enable the change observer for the specified Hype document.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.

Returns

Void

disableChangeObserver(hypeDocument)

Disable the change observer for the specified Hype document.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.

Returns

Void

refreshDescendants(hypeDocument, element, event)

Refresh the descendants of the specified element.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.
element HTMLElement
  • The element.
event Event
  • The event.

Returns

Void

refreshElement(hypeDocument, element, event)

Refresh the specified element.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.
element HTMLElement
  • The element.
event Event
  • The event.

Returns

Void

refresh(hypeDocument, element, event)

Refresh the specified element and its descendants.

Parameters

Name Type Description
hypeDocument HYPE_Document
  • The Hype document.
element HTMLElement
  • The element.
event Event
  • The event.

Returns

Void

refreshDebounced()

Debounced version of above (internal usage)

Returns

Void

setData(data, source, key)

This function allows to set data

Parameters

Name Type Description
data Object

This parameter needs to be an object but it can hold nested values of any type. To use JSON data parse the data before you set it. If you want to store a single value, use the key parameter.

source String

The source is a optional name to store the data. It defaults to the string "shared". If you want to store a single value, use the key parameter.

key String

The key is a optional name to store the data. It defaults to the string "shared". If you want to store a single value, use the key parameter.

Returns

Void

getData(source, key)

This function allows to get data

Parameters

Name Type Description
source String

This the name of the data you want to access. It defaults to the string "shared".

key String

This (optional) key resolves the data given a key

Returns

Returns the object Hype Data Magic currently has stored under the given source name.

refreshFromWindowLevel(hypeDocument)

This function allows to refesh the view from the window level using HypeDataMagic.refresh

Parameters

Name Type Description
hypeDocument Object

This parameter is optional and should be a hypeDocument object to refresh. If no paramter is provided it will refresh all documents found under window.HYPE.documents

Returns

Void

refreshFromWindowLevelDebounced()

Debounced version of above (internal usage)

Returns

Void

setDefault(key, value)

This function allows to override a default

  • source: String that defines the default source name. Defaults to 'shared'.
  • fallbackImage: Function that return a fallback image url or base64 version. Defaults to transparent image.
  • handlerMixin: Object that contains mixins added when calling addHandler. Defaults to {}.
  • sourceRedirect: Object that contains map key:value of source redirects. Defaults to {}.
  • customDataForPreview: Object that contains preview value for custom data (only displayed in IDE). Defaults to {}.

Parameters

Name Type Description
key String

This is the key to override

value String Function Object

This is the value to set for the key

Returns

Void

getDefault(key)

This function returns the value of set default

Parameters

Name Type Description
key String

This the key of the default.

Returns

Returns the current value for a default with a certain key.

trim(str)

This function removes all the white spaces from the beginning and the end of the string

Parameters

Name Type Description
str string
  • The string to be trimmed

Returns

string

  • The trimmed string

resolveKeyToArray(obj, key)

This low level function returns a array resolved based on a string key notation similar to actual code

Parameters

Name Type Description
obj String

This the object the key should act on.

key String

This the key to resolve the object by in string form.

Returns

Returns the current value for a default with a certain key.

resolveObjectByKey(obj, key)

This low level function returns resolves an object based on a string key notation similar to actual code and returns the value or branch if successful

Parameters

Name Type Description
obj String

This is the object the key should act on.

key String

This is key based on notation similar to actual code to resolve the object with. The key can also be provided as a pre-processed array of strings.

Returns

Returns the current value for a default with a certain key.

resolveVariablesInObject(obj, variables, noClone)

Resolve variables in object using resolveVariablesInString recursively and a variables lookup

Parameters

Name Type Description
obj Object
  • The object to resolve variables in
variables Object
  • The variables to use for resolving
noClone Boolean
  • If true, the object will not be cloned before resolving

Returns

Object

The resolved object

resolveVariablesInString(str, variables)

Resolve variables in string using a variable lookup

Parameters

Name Type Description
str string

The string to resolve variables in.

variables object

The variables to resolve.

Returns

string

The resolved string.

cloneObject(obj)

This function clones an object

Parameters

Name Type Description
obj object

Returns

object

copy

findAttribute(element, attr, allowAdditions)

This function finds the value of an attribute on an element or its parents. If the attribute value starts with a '+' then it is added to the value of the attribute on the parent.

Parameters

Name Type Description
element HTMLElement
  • The element to start searching from.
attr string
  • The name of the attribute to search for.
allowAdditions boolean
  • If true, the value of the attribute will be added to the value of the attribute in the parent.

Returns

string

The value of the attribute.

addDataHandler(name, handler)

This function allows to add custom data handler. These following keys can be defined if supplied as an array

  • DataMagicPreviewUpdate: Gets fired only in the IDE
  • DataMagicPrepareForDisplay: Gets fired along HypeScenePrepareForDisplay
  • DataMagicLoad: Gets fired along HypeSceneLoad
  • DataMagicUnload: Gets fired along HypeSceneUnload

If the handler is only set as an functions it defaults to setting DataMagicPrepareForDisplay

Parameters

Name Type Description
name String

The name your handler is identified by in data-magic-handler

handler Function Object

This is either an object with functions or a single function

Returns

Void

resolveDatasetVariables(element)

Resolves the magicSets attribute of an element.

Parameters

Name Type Description
element HTMLElement

The element to resolve the magicSets attribute for.

Returns

Object

The resolved dataset.

assignNew(target, source)

This function only assigns values from source if they are not present in target

Parameters

Name Type Description
target Object
  • The target object
source Object
  • The source object

Returns

Void

debounceByRequestFrame(fn, delay)

Create a debounced function that delays invoking fn until after delay milliseconds have elapsed since the last time the debounced function was invoked.

Parameters

Name Type Description
fn function
  • the function to be debounced
delay number
  • the delay in milliseconds

Returns

function

  • a debounced function

HypeDocumentLoad(hypeDocument, element, event)

HypeDocumentLoad is called when the document is loaded.

Parameters

Name Type Description
hypeDocument HYPE_Document
element Element
event Event

Returns

Void

hypeDocument.refresh(element)

This function allows to refresh the data in the current scene.

This function is useful when you want to refresh the data of the current scene. It will refresh the data of the scene element and all its descendants.

If you want to refresh the data of a specific element, use the function hypeDocument.refreshElement. If you want to refresh the data of all descendant of a given element, use the function hypeDocument.refreshDescendants.

Parameters

Name Type Description
element HTMLDivElement

The element (including descendants) to refresh. This defaults to the scene element.

Returns

Void

hypeDocument.refreshDebounced(element)

This function allows to refresh the data in the current scene. This function is debounced by requestAnimationFrame.

Parameters

Name Type Description
element HTMLDivElement

The element (including descendants) to refresh. This defaults to the scene element.

Returns

Void

hypeDocument.refreshDescendants(element)

This function allows to refresh the data of all descendant of a given element

Parameters

Name Type Description
element HTMLDivElement

The element to start the descendants refresh. This defaults to the scene element.

Returns

Void

hypeDocument.refreshDescendantsDebounced(element)

This function allows to refresh the data of all descendant of a given element. This function is debounced by requestAnimationFrame.

Parameters

Name Type Description
element HTMLDivElement

The element to start the descendants refresh. This defaults to the scene element.

Returns

Void

hypeDocument.refreshElement(element)

This function allows to refresh a specific element

Parameters

Name Type Description
element HTMLDivElement

The element to refresh.

Returns

Void

hypeDocument.refreshElementDebounced(element)

This function allows to refresh a specific element. This function is debounced by requestAnimationFrame.

Parameters

Name Type Description
element HTMLDivElement

The element to refresh.

Returns

Void

hypeDocument.disableChangeObserver()

This function allows to disable observer based refresh calls when updating a data-magic-* attribute

Returns

Void

hypeDocument.enableChangeObserver()

This function allows to (re)enable observer based refresh calls when updating a data-magic-* attribute

Returns

Void

hypeDocument.setContentIfNecessary(element, content)

This function is a simple helper function that checks if the content provided differs from the content found in element.innHTML and only refreshes if needed.

Parameters

Name Type Description
element HTMLDivElement

The element to check

content string

The content to set in innerHTML if it differs

Returns

Void

HypeScenePrepareForDisplay(hypeDocument, element, event)

HypeScenePrepareForDisplay is called when the scene is about to be displayed.

Parameters

Name Type Description
hypeDocument HYPE_Document
element Element
event Event

Returns

Void

HypeSceneLoad(hypeDocument, element, event)

HypeSceneLoad is called when the scene is loaded.

Parameters

Name Type Description
hypeDocument HYPE_Document
element Element
event Event

Returns

Void

HypeSceneUnload(hypeDocument, element, event)

HypeSceneUnload is called when the scene is unloaded.

Parameters

Name Type Description
hypeDocument HYPE_Document
element Element
event Event

Returns

Void

HypeDataMagic()

Properties

Name Type Description
version String

Version of the extension

setData Function

This function allows to set data by passing in an object. An optional data source name can also be used (name defaults to "shared")

getData Function

This function allows to get the data for a specific data source. If no data source name is supplied it defaults to "shared"

refresh Function

This function allows force a refresh on all Hype document from the window level. You can also pass in a specific hypeDocument object to limit the scope.

refresh Function

This function is the same as refresh, but debounced

setDefault Function

This function allows to set a default value (see function description)

getDefault Function

This function allows to get a default value

addDataHandler Function

This function allows to define your own data handler either as an object with functions or a single function

resolveObjectByKey Function

This low level function returns resolves an object based on a string key notation similar to actual code and returns the value or branch if successful. You can also use an array of strings as the key

resolveKeyToArray Function

This low level function returns an array resolved based on a string key notation similar to actual code. Given an array as key it works recursive while resolving the input

resolveVariablesInString Function

This low level function returns a string with all variables resolved. It can also be used to resolve variables in a string.

resolveVariablesInObject Function

This low level function returns an object with all variables resolved. It can also be used to resolve variables in an object.

cloneObject Function

This low level function returns a clone of an object.

debounceByRequestFrame Function

This helper function returns a debounced function.

Returns

Void