Overview of the API

Introduction

Some general considerations about the API of the Atlas toolkit, concerning all bindings. Take also a look to the provided examples; this will help the understanding on how the toolkit works.

Structure of an application

The Atlas toolkit is not based on a special architectural pattern, like MVC related frameworks. So, the structure of an Atlas toolkit based application is rather simple.

launch(...) is the main function. Then, for each user action, through a callback, you have just to perform the appropriate actions on the DOM, like:

  • setting/getting the content of elements ((set|get)Content[s]),
  • handling CSS classes ((add|remove|toggle)Class[es])),
  • enabling/disabling elements ((enable|disable)Element[s]),
  • handling attributes/properties ((get|set)(Attribute[s]|Property)),
  • ...

Most of the DOM related functions are named after they corresponding DOM function, if relevant, or, at least, they refer to the DOM items of same name.

The data-xdh-* attributes

Through the XSL transformation, DOM elements can have special attributes which are handled by the Atlas toolkit.

The data-xdh-onevent(s) attributes

An element can have a data-xdh-onevent attribute, which are of following form:

[event|]action

The value of event can be all the available JS events, without the on prefix. When the given event is launched on the concerned element, the callback registered with the register(...) (Node.js API) function and associate with the tag of value action will be called, or the getAction(...) function (other APIs) will return the corresponding action label.

action alone can be specified, without event, the action is then associated with the default event for the given element. For example, setting data-xdh-onevent="Submit" on a button element is the same as setting data-xdh-onevent="click|Submit", that is, as the onclick event is the default one for a button.

With the data-xdh-onevents attribute (with a final s), several actions on an element can be specified, by enclosing each event|action pair between parenthesis (( )) and separating them with a pipe (|).

The data-xdh-widget

This attribute can be used to dress an element with a jQuery widget.

The form is:

name[|parameters[|retrieving_function]].

The needed CSS and scripts must be put in the head.html file as indicated in the widgets' documentation.

The activation of the widget is made by calling the dressWidgets(...) method of the DOM object. For some widgets, this have to be made after an eventual call to setContent(s) to fill the widgets.

name is the name of the widget. In the documentation of the widget, you often find a instruction such as $(...).function(...);. name is simply function (without the parameters).

parameters are the parameters of the widget you usually given to the $(...).widget(...) instruction, with the enclosing parenthesis. If this parameters contains a parenthesis or a pipe, they must be escaped with the backslash character (\(, \), \|).

For some widget, to retrieve its content, you have to call a special function. In this case, retrieving_function is where you put this function, the parenthesis and pipes escaped with the backslash character (\(, \), \|).

Bindings

The links belows head to the detailed API of the corresponding binding.