Interactions with the DOM
Aria Templates relies heavily on data binding to refresh parts of the interface that need to be updated, which is why you should never feel the need to directly modify the DOM when writing an AT application. There are however very specific cases where manual update of the UI make sense from the code and this article describes them. It explains how to deal with DOM element wrappers and update CSS classes, how to handle focus and scrolling in your application and how to use loading indicators.
While writing your template, you can access and manipulate the DOM elements that are generated by the template markup. This can be done in the template script (but also in the template itself) by calling the method $getElementById.
The returned object is not the DOM element itself. Indeed, direct access to the DOM element is strongly discouraged by Aria Templates. Every DOM element available in templates is wrapped within an instance of the DomElementWrapper class. This allows
- to limit the interaction to a certain set of safe operations,
- to provide cross-browser implementations of commonly used methods,
- enhance the set of actions that can be performed on dom elements.
The argument to provide to the
$getElementById method is an id that you have assigned
- to an element by using the id statement.
- To a section in the section statement. In this case the returned object is of class SectionWrapper, which extends class
DomElementWrapperby adding section-specific methods.
- To a widget. In this case the returned DomElementWrapper is associated to the dom element that contains all the markup generated by the widget.
Consider the following code extracted from a HTML template.
Its associated script could contain the following statements:
It is possible to programmatically set focus on a specific widget or generic dom element from the template script.
Note that it is only possible to do this from the template script of the same template in which the widget/element is defined.
The template script is endowed with the
$focus that receives an id as parameter and sets the focus on the widget/element with that id.
As far as widgets are concerned, each of them can implement a
focus method that will be called whenever you try to set the focus on it.
Suppose you are using a
TextField widget from the
AriaLib widget library in your HTML template:
In the associated template script you can use
which will set the input focus on the text field. A side effect of this is that the browser will scroll to make the focused widget visible to the user, so this feature can also be used to programatically scroll to different parts of the template.
Sub-templates are a very useful widget (
Template widget of the standard
AriaLib widget library).
When you include a template inside another one, you can provide an id and focus on it, as you would do with any other widget.
Suppose you have the following template:
TemplateA includes two other templates (
TemplateC) as sub-templates.
Suppose that, as soon as the template is ready to be displayed, you want to give focus to the sub-template C. You can implement this behaviour in the script associated to template A.
As soon as template A and its sub-templates are ready to be displayed, the
$focus method is called (for more information about the
$displayReady go to this article).
Suppose that template C is defined in the following way:
Basically it has two text fields with id's
What happens when it receives the focus from template A?
You can specify the actions to take after a sub-template is given focus by defining the method
$focusFromParent inside the sub-template script.
For example, suppose that you want to give focus to the textfield with id
You can do that in the template script
If the method
$focusFromParent is not implemented on Template C, then the focus received from the parent template would be cast onto the first focusable element (
TextField with id
"textFieldA" in the above example).
Sometimes it is desirable to set the focus on an element inside the template after the latter is refreshed.
In these cases it is possible to define the method
$afterRefresh in the template script.
$refresh method is called on the template, the
$afterRefresh method is invoked (when it has been defined).
For example, in the
$prototype property of the template A script definition, it is possible to add the method
so that the focus is given to the sub-template C whenever template A is refreshed.
For more information about the
$afterRefresh method go to this article).
In this sample you can see how sub-template A gives focus to the second checkbox after receiving it from the containing template (its script implements the
Sub-template B, instead, does not have any script at all.
This is why the focus is automatically passed over to the first focusable element.
It is possible to get/set the scroll positions of the DOM element that contains the template by using the
setContainerScroll methods from a template script.
This element can be either:
spanwrapping a template widget
divcontainer specified in the
DomElementWrapper class provides methods to control the scroll positions of elements inside a template that can be retrieved using
$getElementId() inside the template script. These methods are:
getScrollwhich returns an object containing the scrollLeft and scrollTop values
setScrollwhich allows to set them
scrollIntoViewwhose purpose is to scroll the element until a certain element contained inside it becomes visible
For more information, check the
Aria Templates allows you to display processing indicators overlays on top of DOM elements. In particular, you can trigger the processing indicator overlay on
- DOM element wrappers
- Generic DOM elements
Once you retrieve a DOM element wrapper through the
$getElementById method, you can use the method setProcessingIndicator method.
Suppose you create a span in your template:
You can then retrieve its associated DOM element wrapper and trigger the display of a processing indicator on top of it:
You can see that it is also possible to provide a message to be displayed on the overlay that contains the processing indicator image.
Remark: the processing indicator is removed when a template refresh occurs.
The processing indicator above a section can be displayed either through a Section Wrapper or by automatically binding it to the data-model.
When you give the id of a section as a parameter of the
$getElementById method, it returns the instance of SectionWrapper associated to the section with the specified id.
SectionWrapper class extends the
DomElementWrapper class, you can trigger a processing indicator on top of the section dom just like you would on any DOM element wrapper.
In the template:
In the template script:
Remark: the processing indicator is removed when a template refresh occurs. If you want to keep the processing indicator through refreshes, you have to bind its presence to the data-model, as explained in next section.
It is possible to use the
bindProcessingTo property of a section configuration in order to specify a piece of data-model to which the presence of a processing indicator should be bound.
Moreover, you can also set a message to be displayed on the overlay in the
In the template:
In the template script:
Aria Templates has a DOM overlay utility that allows to set a processing indicator on top of any DOM element.
This could be useful if you want the overlay on the whole page or on any element that is defined outside of Aria Templates (for example in the
index.html file of your application).
However, make sure you use the API described above if you want to set a processing indicator on top of elements defined within your templates. The utility function should only be used for elements outside Aria Templates.
Suppose you have the following <
body> in your
You can use the following methods (inside any class, module controller, flow controller, template script, ...)
You can see that, after refreshing the template, the loading indicator on the the section with id
"mySecondSection" persists because it is bound to the data-model.
All the other loading indicators are removed.
Aria Templates allows to set an element as draggable and to specify how the element should be dragged.
aria.utils.dragdrop.Drag is the class that defines the element that can be dragged, called draggable element from now on.
The constructor accepts the following arguments
elementis either an id or a DOM element.
paramsis an optional configuration object (also described here) containing:
handleeither an id or a DOM element, this is the element from which the user can start dragging. If not specified it defaults to the draggable element. In the case of a dialog, draggable element is the whole dialog window, while handle is just the title bar.
cursorcss cursor property to be added on the draggable element or the handle. If not specified no default value will be added.
constrainToeither an id or a DOM element, whose boundaries will be used to constrain the movement of the dragged element. It can also be the special value
aria.utils.Dom.VIEWPORTif you want to constrain the movement to the viewport.
axiscan be either "x" or "y" in order to force one-dimensional movement.
proxyconfiguration object for the element that moves with the mouse. This can contain:
typeType of proxy. Possible values are the classes in package
cfgArgument passed to the constructor of the overlay described by type.
aria.utils.dragdrop.Drag is observable through the events
dragstartraised when the user starts moving the draggable element. More in details this is not raised on mousedown but on the first mousemove after a mouse down, in other words when the position actually changes.
dragendraised when the user stops moving the draggable element. This corresponds to a mouseup after a mousemove. This event will also contain the current position of the draggable element.
The default classname of the overlay element is xOverlay. Its style can be changed throught the skinning system by setting the desired background color, opacity and border corresponding to the following skin properties:
aria.templates.general.overlay.backgroundColor=#ddd aria.templates.general.overlay.opacity=40 aria.templates.general.overlay.border=1px solid black
The default opacity is 0.5/1.