This article describes how to use DOM events in Aria Templates. Note that it doesn't cover widgets events for which documentation can be found directly in the widget's reference itself.
Attaching DOM Events to elements created in templates is similar to using the various
on*event* parameters (
onkeypress, ...) in a standard HTML page. It is the most straightforward way to allow user interaction with DOM Elements in Aria Templates.
Events handled in Aria Templates are:
click, dblclick, mouseup, mousedown, mouseover, mousemove, mouseout, mouseenter, mouseleave
keydown, keypress, keyup
- HTML form:
focus, blur, select, change, submit, reset
Please note that all events are not necessarily available on all tags. This depends on how browsers manage DOM events. You may want to read detailed documentation on that topic such as this one for more information.
To attach events to DOM elements in templates you must use the
on statement is part of the element opening tag, as would an
on_event_ property be.
To specify the event handler method you may either use the short or complete notation:
Check the examples section to learn which syntax you should use and when.
You can use several
on statements inside the same DOM element.
The callback method given to your
on statement can be defined either in the template script, the module controller, or an inline anonymous function.
Depending on how you declared it, the scope of the callback (what
this represents) will differ:
- If the event was attached using the short syntax, the scope will be assigned to the template object.
- If the event was attached with the complete syntax, the scope will be the one given in the scope property if any, or will default to the template object. It is however good practice to explicitly declare the scope of your callback even when you intend it to be the template, for readability and maintenance purposes.
A callback assigned with
on must conform to the following signature :
evtis a cross-browser event wrapper detailing the event that triggered the callback.
argsproperty of the callback definition when called with the complete syntax.
In many situations, you will want to check information about the event that was raised.
You may do so by checking the
aria.templates.DomEventWrapper parameter of your callback, thus accessing all the event properties in a cross browser manner (
type, target, altKey, ctrlKey...).
In addition to the usual properties, the DomEventWrapper also gives access to helper methods such as
preventDefault() inherited from the DomEvent class.
target property of a DomEventWrapper is an instance of
Similarly to the DomEventWrapper, it acts as a cross-browser wrapper over the actual DOM element.
Using DOM events is one of the easiest ways to handle user interaction in an Aria Templates application. Here are a few guidelines to keep in mind when using events.
Use event delegation. For performance and maintenance reasons you should avoid setting event listeners on plenty of elements inside a container and rather use one at container level.
An obvious consequence of the first point is: do not create events in loops.
DomElementWrappersfor light changes. If you need to update a CSS class, it is more efficient to using the dedicated methods rather than performing a refresh.
You might want in some cases to attach events to elements outside of your template, like <
body> for instance.
To do so, the
addListener() method of the
aria.utils.Event singleton provides a way bind an event handler to any DOM element.
This first sample page contains various examples of mouse events, with several event types being used : click, mouseover, mouseleave.
This sample is the first of a series of samples all based on a 1-9 keypad. In this first sample, we look at click events. The event handler is designed to be simple : a simple datamodel update followed by a refresh.
This sample is based upon the keypad example used for the Mouse Event sample.
The mouse selection is here replaced with a keyboard navigation using the arrows key.
In this sample, the callback handler takes advantage of the
DomEventWrapper to retrieve the keyCode of the event.
Then using the statics available on
DomEventWrapper, we easily check if the event was triggered by on of the arrow keys or not.
Still based on the keypad example, this sample uses input events such as
As you can see in the template script, the change event is the rough DOM Event, therefore we have to take care of the browser specific behavior of the change event.
On IE, we force a blur before we refresh, to trigger the change event to be fired.
A listener on focus is added and is now responsible for updating the datamodel and trigger the refresh.
Thanks to this new design, the selection updates automatically if the user navigates using the TAB key.
The actual keyboard navigation now triggers a focus on the
DomElementWrapper target of the event.
This example is the exact same as the example 3, but the event handlers have been moved at the topmost element of the template. Before they were repeated in a loop. This allows to use only 3 events for the whole template, instead of 3 per box (27). This can have a pretty significant impact on performances.
The downside is of course that we now have less information directly bound to the event callback. But it is easy enough to compensate for that. One of the first tools of event delegation is to check the tagName of the target, to know if the event was captured on a DOM element that interests us. Indeed, since the event is attached on a container element, it will be fired each time the container receives the event, either directly or by bubbling. Checking the tagName is the easiest way to make sure the event was fired on an element that interests us.
We also need to know what is the index of the clicked input.
To retrieve this information dynamically in the callback, we will use data attributes. data attributes are extra attributes that you can use on a DOM element inside your template and that start with the prefix
Modern browsers provide a specific API to retrieve them from an element. Aria templates provides method
getData on top of instances of
DomElementWrapper. Here we store the index as
Thus, we can retrieve it using
All this overhead has been mutualized in a single method and is used in each event callback of the template script. The rest of the implementation then remains strictly similar to the non-delegated version.
Event delegation is always about striking a good balance between the amount of events and the amount of dynamic processing in the callback.
This sample is again based on the keypad example.
This time, a keydown is attached on the document using the
aria.utils.Event.addListener() utility method.
We filter the numkeys and the matching 1-9 box is selected when the user presses one of those keys.
Note that in the destructor of the template script, the
addListener is mirrored by a
removeListener to avoid leaving unwanted events on the page.