In English

API of the Atlas toolkit (v0.12)


Structure of a program

Although concerning web applications, the Atlas toolkit is not based on a special architectural pattern, like the popular MVC related frameworks. So, the structure of an Atlas toolkit based program is rather simple.

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

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

Take also a look to the provided examples; this will help the understanding on how the toolkit works.

The Atlas toolkit and the DOM

Most of the DOM related functions (all functions presented in this page, unless otherwise specified) are named after they corresponding DOM function, if relevant, or, at least, they refer to the DOM items of same name.

The data-xdh-onevent(s) attributes

An element can have a data-xdh-onevent attribute and/or a data-xdh-onevents.

Values of the data-xdh-onevent 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 an element, the callback registered with the launch(...) function and associate with the tag of value action will be called (or the handle(...) callback for Java) will be called with appropriate arguments.

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", 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 (|).

Global functions (not members of the DOM object)

Below functions are the only ones which are not member of the DOM object.

With following functions, one can build an HTML tree to use with the before, begin, inner, end and after methods described below.

createHTML

  • Java: info.q37.atlas.xdhq.XML createHTML([String rootTag])
  • Node.js: createHTML([rootTag])
  • Perl: createHTML([$rootTag)]
  • Python: create_HTML([rootTag])
  • Ruby: createHTML([rootTag])

Returns an object which can be used to create the HTML data for below before, begin, inner, end and after functions. rootTag will be the label of the root tag of the HTML tree ; if missing, then there would be no root tag.

Following functions are members of this object.

pushTag

  • Java: void pushTag(String tag)
  • Node.js: pushTag(tag)
  • Perl: pushTag($tag)
  • Python: pushyag(tag)
  • Ruby: pushTag(tag)

Creates a new tag of label tag.

popTag

  • Java: void popTag()
  • Node.js: popTag()
  • Perl: popTag()
  • Python: pop_tag()
  • Ruby: popTag()

The parent tag becomes the current one.

putAttribute

  • Java: <Value> void putAttribute(String name, Value value)
  • Node.js: putAttribute(name,value)
  • Perl: putAttribute($name,$value)
  • Python: put_attribute(name,value)
  • Ruby: putAttribute(name,value)

Sets an attribute of name name and value val to the current tag.

putValue

  • Java: <Value> void putValue(Value value )
  • Node.js: putValue(value)
  • Perl: putValue($value)
  • Python: put_value(value)
  • Ruby: putValue(value)

Sets value as value for the current tag.

putTagAndValue

  • Java: <Value> void putTagAndValue(String tag, Value value )
  • Node.js: putTagAndValue(tag, value)
  • Perl: putTagAndValue($tag, $value)
  • Python: put_tag_and_value(tag, value)
  • Ruby: putTagAndValue(tag, value)

Creates a tag with name tag and value value.

With following functions, one can build an XML tree which can be transformed to HTML using an XSL file with the corresponding before, begin, inner, end and after methods described below.

createXML

  • Java: info.q37.atlas.xdhq.XML createXML(String rootTag)
  • Node.js: createXML(rootTag)
  • Perl: createXML($rootTag)
  • Python: create_XML(rootTag)
  • Ruby: createXML(rootTag)

Returns an object which can be used to create the XML data for below before, begin, inner, end and after method. rootTag will be the label of the root tag of the XML tree. Following functions are member of this object.

Other methods

Same as above HTML related functions.

Others

launch

This function launches the event loop of the program. It has an optional headContent parameter which content is put in the head section of the main HTML page of the program.

The createCallback parameter is a function which is called for each new session. This parameter does not exist for Java. For Node.js, this parameter is mandatory and must return a DOM object, or a subclass of it. For the other bindings, the parameter is optional and returns an user-defined object.

callbacks (does not exist for Java) is described for each binding below and has following content. actionx are the actions specified in the data-xdh-onevent(s) attributes, and callbackx, callbacks which receive, in this order:

  • the object returned by createCallback,
  • a DOM object (not for Node.js, for which this object is provide by above parameter),
  • the id of the element which receives the event,
  • the action label.

There must be an entry in callbacks with an empty string as key; the corresponding callback will be called for each new session.

In some examples, extraneous parameters are given to the launch function. For your own developments, you don't need to give this extraneous parameters.

Java
static void launch(info.q37.xdhq.XDH_SHRD.Callback callback [, String headContent])

This is a static method of the info.q37.atlas.Atlas class.

callback is called for each new session, and must return an object which implements the below given handle method.

Node.js
launch(createCallback,callbacks,headContent)

callbacks looks like:

{
    'action1': callback1,
    'action2': callback2,
    'action3': callback3,
    ...
}
Perl
launch(\%callbacks, \&createCallback, $headContent)

callbacks looks like:

{
    "action1" => \&callback1,
    "action2" => \&callback2,
    "action3" => \&callback3,
    ...
}
Python
launch(callbacks,createCallback=None,headContent="")

callbacks looks like:

{
    'action1': callback1,
    'action2': callback2,
    'action3': callback3,
    ...
}

If the createCallback parameter of the launch(…) function is equal to or returns None, the first parameter received by the callbacks is the DOM object, the second, the id of the element which receives the event, and the third, the action label.

Ruby
launch(callbacks, createCallback = -> () {}, headContent="")

callbacks looks like:

{
    "action1" => callback1,
    "action2" => callback2,
    "action3" => callback3,
    ...
}

handle (Java)

With this callback, you implement how the program reacts on the different actions.

For the other bindings, you have to define a callback for each action and give them to the launch function described above, so there is no global callback for all the actions.

@Override public void info.q37.atlas.Atlas.handle(String action, String id)
  • action is the action label defined in the data-xdh-onevent(s) attributes for the element which receives the event,
  • id is the id of this element.

There is also a public object named dom of type q37.info.atlas.DOM, inherited from info.q37.atlas.Atlas, which methods are described below.

broadcastAction

  • Java: void broadcastAction(String action[, String id])
  • Node.js: broadcastAction(action[,id])
  • Perl: broadcastAction($action[,$id])
  • Python: broadcast_action(action,id="")
  • Ruby: broadcastAction(action,id="")

Sends an action of label action and the value of id, (which, by default, is an empty string) to all the clients. You have to create a callback for this action, as for a regular action.

General functions

alert

  • Java: void alert(String message)
  • Node.js: alert(message[,callback])
  • Perl: alert($message)
  • Python: alert(message)
  • Ruby: alert(message)

Displays an alert box with message as message.

confirm

  • Java: boolean confirm(String message)
  • Node.js: confirm(message[,callback])
  • Perl: confirm($message)
  • Python: confirm(message)
  • Ruby: confirm?(message)

Displays a confirmation dialog box with message as message.

The returned value (the parameter given to the callback for the Node.js version) is true when the user clicks the OK (or equivalent) button, and false when the user clicks the Cancel (or equivalent) button.

focus

  • Java: void focus(String id)
  • Node.js: focus(id[,callback])
  • Perl: focus($id)
  • Python: focus(id)
  • Ruby: focus(id)

Gives the focus to element of id id.

flush

  • Java: void flush()
  • Node.js: flush([callback])
  • Perl: flush()
  • Python: flush()
  • Ruby: flush()

Returns (for Node.js, calls callback) only when all the previous DOM related functions were achieved.

Attribute

getAttribute

  • Java: String getAttribute(String id, String name)
  • Node.js: getAttribute(id,name[,callback])
  • Perl: getAttribute($id, $name)
  • Python: get_attribute(id,name)
  • Ruby: getAttribute(id,name)

Returns (gives as parameter to callback for the Node.js version) the value of the attribute named name of the element of id id.

removeAttribute

  • Java: void removeAttribute(String id, String name)
  • Node.js: removeAttribute(id,name[,callback])
  • Perl: removeAttribute($id, $name)
  • Python: remove_attribute(id,name)
  • Ruby: removeAttribute(id,name)

Removes attribute named name from element of id id.

setAttribute

  • Java: void setAttribute(String id, String name, String value)
  • Node.js: setAttribute(id,name,value[,callback])
  • Perl: setAttribute($id, $name, $value)
  • Python: set_attribute(id,name,value)
  • Ruby: setAttribute(id,name,value)

Sets value as value for the attribute named name of the element of id id.

Class(es)

Following methods allows to handle classes (the CSS related class attributes of HTML tags), by respectively add, remove or toggle (i.e. adds if not present, otherwise removes) a class to elements identified by their ids (the content of the id attribute from HTML tags).

The idsAndClasses parameter must have following form:

Java:

new HashMap<String,String>()
{{
    put("id1", "class1");
    put("id2", "class2");
    put("id3", "class3");
    ...
}}

Node.js:

{
    'id1': 'class1',
    'id2': 'class2',
    'id3': 'class3',
    ...
}

Perl:

{
    'id1' => 'class1',
    'id2' => 'class2',
    'id3' => 'class3',
    ...
}

Python:

{
    'id1': 'class1',
    'id2': 'class2',
    'id3': 'class3',
    ...
}

Ruby:

{
    'id1' => 'class1',
    'id2' => 'class2',
    'id3' => 'class3',
    ...
}

addClass

  • Java: void addClass(String id, String class)
  • Node.js: addClass(id,class[,callback])
  • Perl: addClass($id, $class)
  • Python: add_class(id,class)
  • Ruby: addClass(id,class)

addClasses

  • Java: void addClasses((Map<String,String> idsAndClasses)
  • Node.js: addClasses(idsAndClasses[,callback])
  • Perl: addClasses(@idsAndClasses)
  • Python: add_classes(idsAndClasses)
  • Ruby: addClasses(idsAndClasses)

removeClass

  • Java: void removeClass(String id, String class)
  • Node.js: removeClass(id,class[,callback])
  • Perl: removeClass($id, $class)
  • Python: remove_class(id,class)
  • Ruby: removeClass(id,class)

removeClasses

  • Java: void removeClasses((Map<String,String> idsAndClasses)
  • Node.js: removeClasses(idsAndClasses[,callback])
  • Perl: removeClasses(@idsAndClasses)
  • Python: remove_classes(idsAndClasses)
  • Ruby: removeClasses(idsAndClasses)

toggleClass

  • Java: void toggleClass(String id, String class)
  • Node.js: toggleClass(id,class[,callback])
  • Perl: toggleClass($id, $class)
  • Python: toggle_class(id,class)
  • Ruby: toggleClass(id,class)

toggleClasses

  • Java: void toggleClasses((Map<String,String> idsAndClasses)
  • Node.js: toggleClasses(idsAndClasses[,callback])
  • Perl: toggleClasses(@idsAndClasses)
  • Python: toggle_classes(idsAndClasses)
  • Ruby: toggleClasses(idsAndClasses)

Value(s)

Following methods allows to retrieve (give as parameter to the callback for the Node.js binding) or set the content of elements identified by their ids (the content of the id attribute from HTML tags).

The idsAndClasses parameter must have following form:

Java:

new HashMap<String,String>()
{{
    put("id1", "value1");
    put("id2", "value2");
    put("id3", "value3");
    ...
}

Node.js:

{
    'id1': 'value1',
    'id2': 'value2',
    'id3': 'value3',
    ...
}

Perl:

[
    "id1" => "value1",
    "id2" => "value2",
    "id3" => "value3",
    ...
]

Python:

{
    'id1': 'value1',
    'id2': 'value2',
    'id3': 'value3',
    ...
}

Ruby:

{
    'id1' => 'value1',
    'id2' => 'value2',
    'id3' => 'value3',
    ...
}

getValue

  • Java: String getValue(String id)
  • Node.js: getValue(id[,callback])
  • Perl: getValue($id)
  • Python: get_value(id)
  • Ruby: getValue(id)

getValues

  • Java: String[] getValues(String[] ids)
  • Node.js: getValues(ids[,callback])
  • Perl: getValues(@Ids)
  • Python: get_values(ids)
  • Ruby: getValues(ids)

setValue

  • Java: void setValue(String id, String value)
  • Node.js: setValue(id,value[,callback])
  • Perl: setValue($id, $value)
  • Python: set_value(id,value)
  • Ruby: setValue(id,value)

setValues

  • Java: void setValues((Map<String,String> idsAndValues)
  • Node.js: setValues(idsAndValues[,callback])
  • Perl: setValues(@idsAndValues)
  • Python: set_values(idsAndValues)
  • Ruby: setValues(idsAndValues)

Mark ((get|set)Mark[s](…))

Same as Value(s) related functions, but with the data-xdh-mark attribute.

Also, for the getMark[s](…) functions, retrieves the value of the data-xdh-mark attribute of the element with given id, or, if this attribute is not present for this element, the value of the data-xdh-mark attribute of its parent, or, if this attribute is not present for this element, the value of the data-xdh-mark attribute of its parent, and so on…

Element

enableElement

  • Java: void enableElement(String id)
  • Node.js: enableElement(id[,callback])
  • Perl: enableElement($id)
  • Python: enable_element(id)
  • Ruby: enableElement(id)

Enables element of id id.

enableElements

  • Java: void enableElements(String[] ids)
  • Node.js: enableElements(ids[,callback])
  • Perl: enableElements(@ids)
  • Python: enable_elements(ids)
  • Ruby: enableElements(ids)

Enables element of ids ids (array of strings).

disableElement

  • Java: void disableElements(String id)
  • Node.js: disableElement(id[,callback])
  • Perl: disableElement($id)
  • Python: disable_element(id)
  • Ruby: disableElement(id)

Disables element of if id.

disableElements

  • Java: void disableElements(String[] ids)
  • Node.js: disableElements(ids[,callback])
  • Perl: disableElements(@ids)
  • Python: disable_elements(ids)
  • Ruby: disableElements(ids)

Disables element of ids ids (array of strings).

parent

  • Java: String parent(String id)
  • Node.js: parent(id[,callback])
  • Perl: parent($id)
  • Python: parent(id)
  • Ruby: parent(id)

Returns the parent element of element of id id, an empty string if such an element does not exist.

previousSibling

  • Java: String previousSibling(String id)
  • Node.js: previousSibling(id[,callback])
  • Perl: previousSibling($id)
  • Python: previous_sibling(id)
  • Ruby: previousSibling(id)

Returns the previous element of element of id id, an empty string if such an element does not exist.

nextSibling

  • Java: String Sibling(String id)
  • Node.js: Sibling(id[,callback])
  • Perl: Sibling($id)
  • Python: _sibling(id)
  • Ruby: Sibling(id)

Returns the element next to the element of id id, an empty string if such an element does not exist.

firstChild

  • Java: String Child(String id)
  • Node.js: Child(id[,callback])
  • Perl: Child($id)
  • Python: _child(id)
  • Ruby: Child(id)

Returns the first child element of element of id id, an empty string if such an element does not exist.

lastChild

  • Java: String Child(String id)
  • Node.js: Child(id[,callback])
  • Perl: Child($id)
  • Python: _child(id)
  • Ruby: Child(id)

Returns the last child element of element of id id, an empty string if such an element does not exist.

scrollTo

  • Java: void scrollTo(String id)
  • Node.js: scrollTo(id[,callback])
  • Perl: scrollTo($id)
  • Python: scroll_to(id)
  • Ruby: scrollTo(id)

Scrolls to element of id id into the visible area of the browser window.

HTML, or XML/XSL (before, begin, inner, end, after)

  • Java: void <function>(String id, (String|info.q37.xdhq.XML) htmlOrXML, String xslFilename)
  • Node.js: <function>(id,htmlOrXML[[,xslFilename][,callback]])
  • Perl: <function>($id,$htmlOrXML,$xslFilename)
  • Python: <function>(id,htmlOrXML,xslFilename)
  • Ruby: <function>(id,htmlOrXML,xslFilename)

htmlOrXML can be a string, possibly empty, or an object created by the above create[_]HTML(…) or create[_]XML(…) functions.

if xslFilename is absent, htmlOrXML must be HTML, otherwise, it must be XML, which is transformed to HTML by applying the content of the file specified in xslFilename.

The HTML code is applied to the element of id id depending on <function>, which can be:

  • before to put the HTML code before the element,
  • begin to put the HTML code as first child of the element,
  • inner to replace the content of the element with the HTML code,
  • end to put the HTML code as last child of element,
  • after to put the HTML code after the element.

Property

getProperty

  • Java: String getProperty(String id, String name)
  • Node.js: getProperty(id,name[,callback])
  • Perl: getProperty($id, $name)
  • Python: get_property(id,name)
  • Ruby: getProperty(id,name)

Returns (gives as parameter to callback for the Node.js version) the value of property named name of the element of id id.

setProperty

  • Java: void setProperty(String id, String name, String value)
  • Node.js: setProperty(id,name,value[,callback])
  • Perl: setProperty($id, $name, $value)
  • Python: set_property(id,name,value)
  • Ruby: setProperty(id,name,value)

Sets value as value for the property named name of the element of id id.