Simulation Development

Events

There are two kinds of events: UI events such as Mouse and Keyboard event; and custom events that are invoked through code. In the Functions exercise, we saw how to call a h:function using a click event.

There are two parts to an event, a subscriber (which listens for event messages) and a dispatcher (which broadcasts event messages). When a user clicks on a button, the browser dispatches a click event. By default, the event is ignored. When we subscribe the button to the click, we can react to the action that took place.

Custom events

Custom events are events we dispatch in code often to indicate a change in state (Ex. "ready", "created", "modified", etc). The name of the event is up to you. It often represents the state and/or the item dispatching the event.

Example

Let's say we had a input area where the user was to type in their email address.

<h:email></h:email>

We could dispatch an event indicating the email is valid when its state changes from invalid to valid. The event we dispatch might be validationChanged.

<h:email>
    <h:event validation="onValidationChanged" />
</h:email>

We could then listen to that event perform some kind of action depending on the validation state.

<h:function name="onValidationChanged" args="isValid">
    <h:set property="emailIsValid">{{isValid}}</h:set>
</h:function>

timer Exercise: Subscribe to a slide event

In this exercise we are going to take a look at subscribing to events that are dispatched by the slide. These events can be useful when setting up the slide based on other property values.

Launch in your browser http://localhost:8080/sandbox/#/tutorials/events/slide_events_start. It should open a page with "Slide Events Tutorial" displayed.

Open sandbox/slides/tutorials/events/slide_events_start.html in seed-exam in your editor. A function for each event has already been created. When we subscribe a function to an event, we refer the function as an event handler. Notice the name also indicates the event each function will subscribe to.

Slide dispatches two events: slide.events.init and slide.events.ready. To subscribe (or listen) to these events we will use the h:listen virtual.

In h:virtual add the following lines of code:

<h:listen on="slide.events.init" handler="onSlideInit"></h:listen>
<h:listen on="slide.events.ready" handler="onSlideReady"></h:listen>

We are now susbscribed to this slide's events. If you refresh the page in your browser you will see the two event handlers are invoked when each event fires.

You can also open sandbox/slides/tutorials/events/slide_events_finish.html to see the final result.

timer Exercise: Subscribe to a key event

In an simulation exam question, the question item will include several way to accomplish the objective. Novice users often will use the mouse. Advanced user prefer the keyboard. For example, if a question asked you to save a document, you could use the mouse and click on the save button; or you could use your keyboard and use the combination keys CTRL+S. As an item developer, you must program the simulation to handle these situations.

In this exercise we will add a h:hotkey to handle the key combination of CTRL+K as an example.

Launch in your browser http://localhost:8080/sandbox/#/tutorials/events/slide_events_start. It should open a page with "Slide Events Tutorial" displayed.

Open sandbox/slides/tutorials/events/key_events_start.html in seed-exam in your editor. As in the previous exercise, a function for the event has already been created.

In h:virtual add the following line of code:

<h:hotkey on="command+k, ctrl+k" handler="onKeyEvent"/>

Notice that there are actually two key combinations assigned to the same hotkey. The command+k is for a Mac, while the ctrl+k is for Windows. By pressing either will invoke the event handler and an alert will display.

You can also open sandbox/slides/tutorials/events/key_events_finish.html to see the final result.

timer Exercise: Subscribe to a custom event

So far, we have subscribed to events that already exist. Now we will define our own event and subscribe to it. In order for an event handler to be invoked, we must dispatch the event. We will do this from a function using the h:dispatch action.

Launch in your browser http://localhost:8080/sandbox/#/tutorials/events/slide_events_start. It should open a page with "Custom Events Tutorial" displayed.

Open sandbox/slides/tutorials/events/custom_events_start.html in seed-exam in your editor. As in the previous exercise, a function for the event has already been created.

This example is where we left off in the Functions tutorial. When you click on the button, it displays an alert.

Define a custom event

There is not setup needed to create a custom event. You just need to dispatch it. We are going to dispatch our custom event from the onClick event handler. Add the following line right below h:alert.

<h:dispatch event="my.event" />

Note: The event name my.event could have been anything. It just needs to be a unique string.

Define an event handler

We have not just defined a custom event. The next step is to have something subscribe (or listen) to our event. We are going to create a new function (or event handler). Add the following lines of code below the onClick function

<h:function name="onCustomEvent">
    <h:alert>Custom event called.</h:alert>
</h:function>

When called, it will display an alert.

Subscribe event to event handler

Now we need to bind our event to an event handler using the h:listen virtual. Add the following line below our newly created custom event handler.

<h:listen on="my.event" handler="onCustomEvent"/>

Once you refresh the page and click on the button, you will see the chain of events occur.

You can also open sandbox/slides/tutorials/events/custom_events_finish.html to see the final result.