Extension that easily offers to listen to a multitude of events and execute code based on these events. The declaration is as simple as assigning a key and value in the attributes panel (using data attributes). Furthermore, it offers code execution through the Custom Behavior interface.
Introduction
The extension consists of two parts, being Actions and Events. The action part was born out of the necessity to trigger Hype functions and was in a first alpha used in Hype Gesture (only a simple string parser). Now, Actions have matured to be full JavaScript, adding additional benefits in the process. One of them being, small JavaScript snippets wrapped in a Hype Function, only doing some little thing and not worth a full Function in the resource library. The main action related function to consider is:
HypeActionEvents.triggerAction(code, options)
Code can be an JavaScript statement or just a simple function call. For example:
hypeDocument.triggerAction("startTimelineName('mainTimeline')")
hypeDocument.triggerAction("myFunction()")
hypeDocument.triggerAction("counter=0")
The second parts are events that trigger actions for you, without you having to use hypeDocument.triggerAction
. This part is certainly the most prevalent to grow in coming releases, but already supports a bunch of use-cases. You can trigger actions whenever you have access to the custom behavior. This would include the Actions inspector, Scene Inspector, Symbol Inspector and the Timeline Actions.
Hype Action Events allows for any type of variables and offers a magic rule set: If a variable is not existent in execution context, it will be created on the fly. In the following example, the variable counter
didn't exist previously, and will now be created in hypeDocument.customData
and any subsequent actions referencing it will modify the value there.
Under the hood, variables are mapped to hypeDocument.customData
.The example illustrates creating a counter
variable using On Prepare For Display using the Scene Inspector
Going forward, we can now modify the counter
as seen in the next screenshot. The variable counter
is being incremented and then assigned to innerHTML
of an rectangle with the id "display
". Furthermore, on every fifth count, startTimelineNamed('bounce')
is triggered.
Screenshot using Hype Action Events in the Trigger Custom Behavior interface, in this case it is the Actions Inspector panel.
Example_Code_in_Custom_Behavior.hype.zip (19,7 KB)
One thing that should be interesting to anybody whoever used the Hype API is, that the prefix hypeDocument
is missing. To save space, the triggerAction
interface offers a "smart" and direct access to the function by creating an execution context. This context depends on and is mostly hypeDocument
, but can also be symbolInstance
given the location and way hypeDocument.triggerAction
is used.
Bound Hype functions
To further reduce complexity and length of code snippets, Hype function found under hypeDocument.functions()
can be called using the short form as they are automatically bound to hypeDocument
, element
and event
of the current context. This means hypeDocument.functions().test(hypeDocument, element, event)
becomes a simple test()
call.
Hype or Symbol API
Always available are all function found in hypeDocument
(Hype Document API) or the symbolInstance
(Symbol Instance API) depending on the calling context and all functions found under hypeDocument.function()
in a bound manner. All the methods there in can be called directly (like startTimelineNamed
etc.).
Contextual variables
Even though there is some Proxy magic at work, you can always use explicit contextual variables to be sure what you're accessing.
In the spirit of saving space, these explicit contextual variables are offered in a shorthand form and automatically available in an triggerAction
context.
-
$ctx
Contains the entire context variables, like hypeDocument -
$doc
Is a reference to the currenthypeDocument
API -
$sym
Is a reference to the closestsymbolInstance
API -
$elm
Contains theelement
currently in question (if available) -
$evt
Contains theevent
currently in question (if available)
Since v1.0.6
-
hypeDocument
Is a reference to the current document API -
element
Contains theelement
currently in question (if available) -
event
Contains theevent
currently in question (if available)
Even if the original signature is a little long for attribute notation, it is now supported to allow transferring code back and forth between the code editor and direct notation in data attributes easier
Options when trigger actions
Some cases require you to pass some variables in the options like the element
or event
when called directly from JavaScript.
hypeDocument.triggerAction (code, {
element: element,
event: event
});
Here is a list of all the current options that can be passed in:
-
element
Used for Hype function binding and to find the closestsymbolInstance
-
event
Used for Hype function binding -
symbolInstance
This can be used to pass in a customsymbolInstance
-
strictMode
This boolean can be set to force a strict mode for code execution. Removes the execution context and applies all the restrictions entailed with"use strict;"
Subscribing to events using data attributes
It is possible to subscribe specific DOM events using data attributes. The full list out of the box is:
// mouse events ( MouseEvent ):
mousedown, mouseup, click, dblclick, mouseover, mousewheel, mouseout, contextmenu, mousemove,
// Touch events ( TouchEvent ):
touchstart, touchmove, touchend, touchcancel,
// Keyboard events ( KeyboardEvent ):
keydown, keypress, keyup,
// Form events:
focusin, focusout, change, submit,
new since 1.0.3
// Form events:
input, beforeinput,
// CSS animations
animationstart, animationiteration, animationend, animationcancel
// CSS transitions
transitionstart, transitionrun, transitionend, transitioncancel,
// Pointer events
pointerdown, pointerup, pointerover, pointerout,
pointermove, pointerenter, pointerleave, pointercancel
Event bubbling visualized for DOM Events
As seen in the chart, events are emitted on the element and bubble down to the base of the Hype document. The event handler there extracts the code from the data attribute and passes it on to triggerAction
to be processed.
Subscribing to Matter events using data attributes
Furthermore, you can subscribe elements to Matter events being:
// matter events
collision-start, collision-end, collision-active
Subscribing to Hype events using data attributes
It is possible to subscribe elements to multiple Hype events using data attributes. The list of currently supported Hype events is as follows.
new since 1.0.2
scene-load, scene-unload, scene-prepare, layout-request
new since 1.0.6
behavior
Also, allowing to subscribe to specific behavior: behavior names are lower cased and spaces/tabs are replaced with dash. Hence, a behavior like Hello World --- Test
would become hello-world-test
and the full action hook would be data-behavior-hello-world-test-action
Subscribing to Window events using data attributes
new since version 1.0.3
// window
window-resize, window-focus, window-blur,
// printing
window-beforeprint, window-afterprint,
// javascript
window-error,
// other
window-storage,
// connection
window-online, window-offline,
// history
window-hashchange, window-popstate,
// communication
window-message,
// input
window-wheel
Subscribing to Document events using data attributes
new since version 1.0.3
// tabs
document-visibilitychange, document-scroll,
// fullscreen
document-fullscreenchange,
Event handling on global document and window events
As seen in this chart, global events are captured on the Hype scene base and the appropriate event handler searches for elements in the scene subscribing to the particular event and forwards the code to triggerAction
to be processed.
Subscribing to Mutation Observer events using data attributes
new since version 1.0.3
// mutation action
data-mutation-action
// optional modifier
data-mutation-child-list, data-mutation-attributes, data-mutation-character-data, data-mutation-subtree, data-mutation-attribute-filter
// optional modifier to user other target then current element
data-mutation-target
Subscribing to Intersection Observer events using data attributes
new since version 1.0.3
// intersection action
data-intersection-action
// optional modifier
data-intersection-root, data-intersection-margin, data-intersection-threshold
// optional modifier to user other target then current element
data-intersection-target
Subscribing to Resize Observer events using data attributes
new since version 1.0.3
// resize action
data-resize-action
// optional modifier to user other target then current element
data-resize-target
Subscribing to Animation Frame events using data attributes
new since version 1.0.3
// animation frame action
data-animation-frame-action
Subscribe to a supported event using a data attribute
To subscribe, add a data attribute to an element as follows: data-EVENT-action
.
For example, to subscribe and element to a click event, you would add an attribute called data-click-action
and set the value to some code like alert("You clicked me!");
.
Example_Trigger_Action_with_Data_Attribute.hype.zip (35,8 KB)
I intentionally also chose click
to illustrate the difference of these DOM events versus using built in Actions under the Actions Inspector. There is not a full parity, but some overlap. Hype Action Events are bound to a bubbled event and don't include fallback logic like interpreting a click as a touch given the device type. Subscribing through the data attribute is in these cases very explicit and intentional. In other cases, Hype Action Events offers events not easily available and manages the listeners. This is only scratching the surface … more documentation coming soon
Error handling in Hype Action Events
Errors are trapped in a try/catch block and in production fail silently. When previewing your code in the browser directly from Tumult Hype you get information about errors directly in the console:
For example, In this case a user has probably misspelled a function name!
This is the information you are being shown:
- You can see the version number of Hype Action Events you're using (good for requesting help)
- You are shown the code fragment that is causing the error
- You get the error that is caused by the fragment. In case of functions calls, the error might be emanating from withing the function
- The element this fragment is attached to is listed (if possible) hovering over it will reveal it in the browser window (if currently visible)
If you need the error information after you have exported your Hype project or need to debug on a production system, you can always force errors to be shown by setting:
HypeActionsEvents.setDefault('debug', true);
Hope this helps!
Release on GitHub: