Events

Overview

You can use visual Prysm events to make your content from Animate interactable. This saves time by avoiding the need to manually write JavaScript code.

Events are located in the events tab.

You can add any number of events and script the behavour of elements.

To add an event to the element you should first select a symbol.

Document events

Also you can add an events to the document using the document tab. This will attach the event listeners in the exported HTML to the document. Document events are usually global per-page events.

To add an event to the document you don't need any selected symbol.

For more information about events in JavaScript you can check: Here.

Supported event types

For the document events there is one more event type:

The CUSTOM-BOUND event type is not a supported document event!

Custom event

The custom event type is used to add a custom event to an element. What are custom events you can check here.

To add a CUSTOM event from the panel you can do the following:

  1. Navigate to the Events tab and select an event - CUSTOM.
  2. Name the custom event by typing whatever name you want inside the Event name input field.
  3. Add a new handler.
  4. Select a javascript handler for example.
  5. Open JavaScript editor.
  6. Type console.log('custom event handler') inside the editor and save.

Export a custom event

Exporting a custom event will lead to generation of the following lines of code to the JavaScript file:

${element}.addEventListener(${custom event name added from the panel}, (event) =>{
    // the handlers added from the panel will be generated here
});

The result of exporting the example above is:

element.addEventListener("customEventName", (event) =>{
    const eventTarget = event.currentTarget;

    console.log('custom event handler');
});
If you check Export as data-bind-events checkbox the CUSTOM events won't be exported! This is happening because we export all the events inline in the HTML to work with the generated element from binding. In the standard HTML, there are no inline custom events! To resolve this problem we added the next type of events - CUSTOM-BOUND.

Custom bound event

Custom bound event is similar to the custom event but this type is used to attach custom events to elements generated with data binding. This event type is working in the panel similar to the custom event - adding event name, adding handlers and etc.

The differences are:

  • To make working custom events on elements generated with binding we use the custom binding attributes feature added in the Player.
  • We generate custom attribute for the element on which is attached CUSTOM-BOUND event in the exported HTML - <div data-bind-some-attrubute=""></div>.

  • If the user wants to pass a value, model or iterator via the custom bind attribute, that we generate for the element, then the Bind value input can be used for this purpose.

    • In this input, you can type a valid data-bind expression which will be evaluated from the Player.
    • Typing {{iter}}, for example, inside this input will result in the HTML to - <div data-bind-some-attrubute="{{iter}}"></div>.
If you check Export as data-bind-events the CUSTOM-BOUND events won't be affected! They will be exported without any change!

Example

For this example, we will use a symbol with the name Symbol 1. First of all select this symbol!

To add a CUSTOM-BOUND event to an element using the panel you need to:

  1. Navigate to the Events tab and select an event - CUSTOM-BOUND.
  2. Name the custom event by typing whatever name you want inside the Event name input field.
  3. Add a new handler.
  4. Select a javascript handler for example.
  5. Open JavaScript editor.
  6. Type console.log('custom bound event handler') inside the editor and save.
  7. Add a bind value for the currently selected element
    • This value will be used in the generated custom attribute

When you export the result will be the following:

  • HTML - <div data-bind-Symbol-1="{{iter}}" where Symbol-1 is the symbol name.
  • JavaScript

For registering the custom attribute we will export a class holding the state of the attribute value, update and init method which will be used to update the state and attach the custom event to the element.

class Symbol_1 {
    constructor() {
        this.state = null;
    }

    update(element, value) {
        this.state = value;
    }

    init(element, value) {
        element.addEventListener("customEventName", (event) => {
            const eventTarget = event.currentTarget;
            console.log('custom bound event handler')
        });
    }
}

To register the newly created attribute we will use the engine.registerBindingAttribute method.

engine.on('Ready', () => {
    engine.registerBindingAttribute("Symbol-1", Symbol_1);
});

What is {{iter}} and more about the data-binding in the Player you can check here. Also you can check our section about the data-binding here

Event handlers

Default handlers

Handlers for playing an animation

Show/Hide handler

Show and hide handlers are used to show or hide the target element.

Options

  • Target - Specify the event target.
    • Self - Will show/hide the current selected element.
    • Other - Will expand more options for the target element.

Extended options

  • Targets query root - Specify from where the targets will be queried.

    • Self - The list with target names will be generated starting to query from the current selection timeline.
    • Root - The list with target names will be generated starting to query from the main (Scene) timeline.

  • Target name - Specify the target element which will be shown/hidden.

List will include all the elements instantiated with an instance name.
  • Show/Hide all targets - Specify if all the elements with instance name choosen from the target list should be shown/hidden.
    • Checked - Will show/hide all the encounters.
    • Unchecked - Will show/hide the first encounter.
This option is convenient because you may have instances with duplicated names.

Example

  1. Let's create two symbols which will behave as a buttons - "Show" and "Hide".

  2. Add instance name - "HideElement" to the "Hide" symbol. alt text

  3. Select the symbol named "Hide" and go to the Events tab.

  4. Add a "CLICK" event and a "Hide" handler.

  5. In the handler options select the target to be "Self". alt text

  6. Select the symbol named "Show" and go to the Events tab.

  7. Add a "CLICK" event and a "Show" handler.

  8. Set the following handler options:

    • Target: "Other".
    • Targets query root: "Root".
    • Target name: "HideElement (Hide)". alt text

  9. Export and preview the result.

Play/Pause handler

Play and pause handlers are used to play or pause the animation of the target element.

Options

  • Target - Specify the event target.
    • Self - Will play/pause the current selected element animation.
    • Other - Will expand more options for the target element.

Extended options

  • Targets query root - Specify from where the targets will be queried.

    • Self - The list with target names will be generated starting to query from the current selection timeline.
    • Root - The list with target names will be generated starting to query from the main (Scene) timeline.

  • Target name - Specify the target element which animation will be played/paused.

List will include all the elements instantiated with an instance name.
  • Play/Pause all targets - Specify if all the animations of the elements with instance name chosen from the target list should be played/paused.
    • Checked - Will play/pause all the encounters.
    • Unchecked - Will play/pause the first encounter.
This option is convenient because you may have instances with duplicated names.

Example

  1. Let's create two symbols which will behave as a buttons - "Play" and "Pause".
  2. Create a symbol - "Animation" with instance name "AnimationElement" and add a Motion tween to it in the main (Scene) timeline.
  3. Enter in the "Animation" timeline.

  4. Convert shape to symbol with name "AnimationNested" and create a Classic Tween for it.

  5. Select the symbol named "Play" and go to the Events tab.

  6. Add a "CLICK" event and a two "Play" handlers.
  7. Set the following options for the first handler - This handler will play all the animations in the main (Scene) timeline.
    • Target: "Other".
    • Targets query root: "Self"/"Root" - doesn't matter.
    • Target name: "Current scene".

  8. Set the following options for the second handler - This handler will play all the animations in the "Animation" timeline.

    • Target: "Other".
    • Targets query root: "Other".
    • Target name: "AnimationElement (Animation)". alt text

  9. Repeat the steps from 3. to 6. for the symbol named "Pause" with handlers type - "Pause". alt text

  10. Select the "AnimationElement" and add a "CLICK" event.

  11. Add "Play" handler with the following options - This will play the animation in "Animation" timeline (The Classic Tween we've created in step 4.).

    • Target: "Self". alt text

  12. Export and preview the result.

GotoAndPlay/GotoAndStop handler

GotoAndPlay and GotoAndStop handlers are the same as Play/Pause but you have the option to choose a label name from where you want to play or to where you want to pause the animation.

Options

  • Target - Specify the event target.

    • Self - Will play/pause the current selected element animation.
    • Other - Will expand more options for the target element.

  • From - Specify from where/where the animation will be played/stopped.

    • Accepts label names from the selected target's timeline.
Duplicate labels in the same timeline are shown only once in a label input. All duplicates are overwritten by the topmost input.

Extended options

  • Targets query root - Specify from where the targets will be queried.

    • Self - The list with target names will be generated starting to query from the current selection timeline.
    • Root - The list with target names will be generated starting to query from the main (Scene) timeline.

  • Target name - Specify the target element which animation will be played/paused.

List will include all the elements instantiated with an instance name.
  • Play/Pause all targets - Specify if all the animations of the elements with instance name choosen from the target list should be played/paused.
    • Checked - Will play/pause all the encounters.
    • Unchecked - Will play/pause the first encounter.
This option is convenient because you may have instances with duplicated names.

Example

We will extend the sample created in Play/Pause section.

But before that we will:

  • Reuse "Play" and "Pause buttons" - You can create a new ones or just duplicate the existing ones.
  • Change the text of the buttons with "GotoAndPlay" and "GotoAndStop".
  • Reuse the symbol "Animation" and its animations.

After this is done we can continue with the other steps:

  1. In the main (Scene) timeline create a new Layer - "Labels".

  2. Add "start", "mid" and "end" label names corresponding to 1st, 13th and 25th frame boxes. alt text

  3. Do the same in the "Animation" timeline. alt text

  4. Select the symbol named "GotoAndPlay" and go to the Events tab.

  5. Add a "CLICK" event and a two "gotoAndPlay" handlers.
  6. Set the following options for the first handler - This handler will play all the animations in the main (Scene) timeline starting from "mid" label.
    • Target: "Other".
    • Targets query root: "Self"/"Root" - doesn't matter.
    • Target name: "Current scene".
    • From: "mid".

  7. Set the following options for the second handler - This handler will play all the animations in the "Animation" timeline starting from "mid" label.

    • Target: "Other".
    • Targets query root: "Other".
    • Target name: "AnimationElement (Animation)".
    • From: "mid". alt text

  8. Repeat the steps from 4. to 7. for the symbol named "GotoAndStop" with handlers type - "gotoAndStop".

  9. Change From handler options to be the "start" frame label - This will stop the animation in the "start" label. alt text

  10. Export and preview the result.

PlayFromTo handler

PlayFromTo handler is the same as GotoAndPlay/GotoAndStop but here you have an option to choose from where the animations will start and where they will stop using the label names. This allows you to play an animation between two different times.

Options

  • Target - Specify the event target.

    • Self - Will play/pause the current selected element animation.
    • Other - Will expand more options for the target element.

  • From - Specify from where the animation will be played.

    • Accepts label names from the selected target timeline.

  • To - Specify where the animation will be stopped.

    • Accepts label names from the selected target timeline.

Extended options

  • Targets query root - Specify from where the targets will be queried.

    • Self - The list with target names will be generated starting to query from the current selection timeline.
    • Root - The list with target names will be generated starting to query from the main (Scene) timeline.

  • Target name - Specify the target element which animation will be played.

List will include all the elements instantiated with an instance name.
  • Play all targets - Specify if all the animations of the elements with instance name choosen from the target list should be played.
    • Checked - Will play/pause all the encounters.
    • Unchecked - Will play/pause the first encounter.
This option is convenient because you may have instances with duplicated names.

Example

We will extend the sample created in GotoAndPlay/GotoAndStop section.

But before that we will:

  • Reuse one of the "GotoAndPlay" or "GotoAndStop" buttons - You can create a new one or just duplicate the existing one.
  • Change the text of the buttons with "PlayFromTo".
  • Reuse the symbol "Animation" and its animations.
  • Reuse the Layer with label names.

After this is done we can continue with the other steps:

  1. Select the symbol named "PlayFromTo" and go to the Events tab.
  2. Add a "CLICK" event and a two "playFromTo" handlers.
  3. Set the following options for the first handler - This handler will play all the animations in the main (Scene) timeline starting from the "start" label and finish in the "mid" label.
    • Target: "Other".
    • Targets query root: "Self"/"Root" - doesn't matter.
    • Target name: "Current scene".
    • From: "start".
    • To: "mid".

  4. Set the following options for the second handler - This handler will play all the animations in the "Animation" timeline starting from the "start" label and finish in the "mid" label.

    • Target: "Other".
    • Targets query root: "Other".
    • Target name: "AnimationElement (Animation)".
    • From: "start".
    • To: "mid". alt text

  5. Export and preview the result.

JavaScript handler

A JavaScript handler is used to add a custom JS code to the event. To type the code, a JavaScript Editor window will open.

Example

We will extend the sample created in PlayFromTo section. What we will gonna do is that when playing the animation finishes we will log a message "Animation finished" using console.log.

  1. Select the "PlayFromTo" button.
  2. Check "Wait to finish" checkbox.
  3. Add "JavaScript" handler and click the button near the bin icon.

  4. In other window a text redactor will be opened. There type the following code: console.log('Animation finished!');. alt text

  5. Export and preview the results - Click on the button and wait the animation to finish. Then check the console. alt text

JavaScript file handler

JavaScript file handler is used to call a function from external file.

To add a JavaScript file navigate to the **"Document tab"** and use the plus button in JavaScript files containter.

Example

We will extend the sample created in PlayFromTo section. What we will gonna do is that when playing the animation finishes we call a function from external JavaScript file.

  1. Create a new JS file named "message.js" with the following content:

    function onFinish(message) {
    console.log(message);
}

  2. Navigate to the "Document tab" and add this file.

  3. Select the "PlayFromTo" button.
  4. Check "Wait to finish" checkbox.
  5. Add "message.js" handler (JS file will be listed as a handler option in the handler list).
  6. Select the "onFinish" method.

  7. Type in the "message" parameter - "Animation finished!".

  8. Export and preview the results - Click on the button and wait the animation to finish. Then check the console.

Export as data-bind-events options

A checkbox in the events tab defines whether events will be exporter as data-bind events. All the events added in the events tab will be exported as data-bind-events when this checkbox is checked.

We've created this option to extend the simple UI made in the Binding tab for data-bind-events.

Furthermore, there is an input for the bind value used to pass a model or iterator to the binding event. This is needed if you want to access any model or iterator in the generated event callback.

Bind value accepts a valid binding expression. This expression could be {{model}}, {{iter}} if the element is generated via bind-for or {{#(alias)}} if you have defined any alias via document tab or binding tab.

You can read more about the data-binding models and iterators from bind-for here.

You can read more about the data-binding aliases here.

Example results

  • If the "Export as data-bind-events" option is off the events will be exported as normal event listeners.

    <div class="layoutStyle7 positionStyle9 Symbol-1" cl-labels-key="Symbol-1">
    <div class="visualStyle1 layoutStyle2 positionStyle0"></div>
</div>

//Inside the generated CLEvents.js

const symbol_Symbol_1 = document.getElementsByClassName("Symbol-1");

//click event for Symbol_1
for (let i_0 = 0; i_0 < symbol_Symbol_1.length; ++i_0) {
    symbol_Symbol_1[i_0].addEventListener("click", (event) => {
        const eventTarget = event.currentTarget;
        console.log("Hello world!")
    });
}

  • If the "Export as data-bind-events" option is on and the Bind value input is empty the events will be exported as inline HTML events.

    <div class="layoutStyle7 positionStyle9 Symbol-1" onclick="cb_0(event);" cl-labels-key="Symbol-1">
    <div class="visualStyle1 layoutStyle2 positionStyle0"></div>
</div>

//Inside the generated CLEvents.js

const symbol_Symbol_1 = document.getElementsByClassName("Symbol-1");

//Callback for click in Symbol_1
function cb_0(event) {
    const eventTarget = event.currentTarget;
    console.log('Hello world')
}

  • If the "Export as data-bind-events" option is on and the Bind value input has a binding expression typed in the events will be exported as a data-bind-[eventName].

    <div class="layoutStyle7 positionStyle9 Symbol-1" data-bind-click="cb_0(event, this, {{model}});" cl-labels-key="Symbol-1">
    <div class="visualStyle1 layoutStyle2 positionStyle0"></div>
</div>

//Inside the generated CLEvents.js

const symbol_Symbol_1 = document.getElementsByClassName("Symbol-1");

//Callback for click in Symbol_1
function cb_0(event, element, model) {
    const eventTarget = event.currentTarget;
    console.log('Hello world')
}

The last example illustrates how you can access events, elements or models inside the handler, where the model is associated with the evaluated binding expression you've typed inside the Bind value input.

Example

The following example will illustrate how you can attach a click event on different buttons, using different binding models via binding aliases and how you can access different models' properties.

Prerequisites

  1. A JavaScript file with the different models should be created and a method "playSound" which will be used for logging the soundId and the contextId.

    const buttonModel = {
    soundId: 1,
    contextId: 1,
    color: 'red'
}

const buttonModel2 = {
    soundId: 2,
    contextId: 2,
    color: 'green'
}

engine.createJSModel('buttonModel', buttonModel);
engine.createJSModel('buttonModel2', buttonModel2);
engine.synchronizeModels();

function playSound(eventTarget, soundId, contextId) {
    console.log('soundId: ' + soundId);
    console.log('contextId: ' + contextId);
    console.log(eventTarget.className);
}

  2. The file should be attached to the document via the Document tab. Also, you need the cohtml.js file to be attached to the document tab.

After you are done with the prerequisites you can continue with the actual example.

  1. Create a symbol "Symbol 1" and navigate to the Bindings tab.

  2. Add two aliases

    • alias name - alias1 and alias value - buttonModel.

    • alias name - alias2 and alias value - buttonModel2.

  3. Enter in the "Symbol 1" timeline.

  4. Create a symbol "Btn1" and navigate to the Events tab.
  5. Check "Export as data-bind-events".
  6. Add a Bind value - {{#(alias1)}}.
  7. Add a CLICK event with handler model.js.
  8. Select playSound method from the functions dropdown.

  9. Fill the input fields for the methods params.

    • eventTarget - eventTarget
    • soundId - model.soundId

    • contextId - model.contextId

  10. Create another symbol in "Symbol 1"'s timeline - "Btn2" and navigate to the Events tab.

  11. Redo steps 5 to 9 with Bind value type - {{#(alias2)}}.

  12. Export and preview the result

You can find an example fla file and the resulting documents - here.

Events on elements created using bind-for

If you want to add events from the pannel to an element which is generated using bind-for you should check the option inside Events options container - Export as data-bind-events. This is necessary because without this option choosen the events won't be attached to this element - listeners will try to be added before the models are synchronized. Doing this you will have working events on the dinamically generated elements.

How to use

  • Let Wrapper is the symbol where the elements will be generated using data-bind-for.

  • Element is a symbol inside wrapper and having data-bind-for with value item:{{model.arrayOfItems}} for example.

    • The model is having the following structure for example:
      var modelData = {
    arrayOfItems: [],
};

for (let i = 0; i < 40; i++) {
modelData.arrayOfItems.push({ value: 1 });
}

engine.createJSModel('model', modelData);
engine.synchronizeModels();

  • Inside Element there is Circle symbol with animation inside it's timeline.

  • If you want to play this animation you will add event to the Circle symbol via Events tab - for example Click event with handler play self.
  • If you export you will realize that when you click the Circle element the animation won't be played.
  • Turn back to the Events tab, select Circle symbol and check the option - Export as data-bind-events.

  • Now check the results - When you click on some of the Circle elements the animation inside it will be played.