API (en)

API of the Atlas toolkit (v0.13) #

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 xdh: prefix now replaces the old deprecated (but sometimes still used) data-xdh- prefix.

The xdh:onevent(s) attributes #

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

Values of the 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 xdh:onevent="Submit" on a button element is the same as setting xdh:onevent="click|Submit", as the onclick event is the default one for a button.

With the 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: createHTML([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: pushTag(tag)
  • Ruby: pushTag(tag)

Creates a new tag of label tag.

popTag #

  • Java: void popTag()
  • Node.js: popTag()
  • Perl: popTag()
  • Python: popTag()
  • 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: putAttribute(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: putValue(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: putTagAndValue(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: createXML(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 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 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: broadcastAction(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.

setSupplier #

  • Python: setSupplier(supplier)

supplier is a function which is launched with, as parameter, the URL corresponding to the application.

supplier can also be one of following string:

  • none: nothing happens,
  • auto: the application’s interface is automatically opened in a web browser; this is the default behavior,
  • qrcode: a clickable QR code is displayed in a browser, which can be scanned with smartphones, tablets… to open the application on it.

If supplier is a function, it can return a value which matches and will then be used like the above supplier parameter.

NOTA: the value of the ATK environment variable will override the one given to this function.

getAppURL #

  • Python: getAppURL(id="")

Returns the URL of the application, which, when opened, will launch a new session for this application.

if id is not empty, the function associated to the connect event (the one with the empty label) will have its id parameter set to the given value.

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.

hold (Node.js >= 0.13.2 only) #

  • Node.js: hold()

If you call a dom related method without a callback or a callback which does not call a dom related method before it returns, and later (asynchronously) call a dom related method, you will have an Out of frame function call! error.
To avoid this, you have to use this hold() in case of a missing callback, or call this function before the callback returns in the other case.

log #

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

Displays the message message in the web console.

Attributes #

getAttribute #

  • Java: String getAttribute(String id, String name)
  • Node.js: getAttribute(id,name[,callback])
  • Perl: getAttribute($id, $name)
  • Python: getAttribute(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: removeAttribute(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: setAttribute(id,name,value)
  • Ruby: setAttribute(id,name,value)

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

Classes #

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: addClass(id,class)
  • Ruby: addClass(id,class)

addClasses #

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

removeClass #

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

removeClasses #

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

toggleClass #

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

toggleClasses #

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

Values #

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).

For a group of radio buttons that have the name attribute at the same value, if this value is given to the xdh:radio attribute of the element whose identifier is given to the getValue(s)(...) method, then the value of the value attribute of the selected radio button is returned.

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: getValue(id)
  • Ruby: getValue(id)

getValues #

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

setValue #

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

setValues #

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

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

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

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

Elements #

enableElement #

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

Enables element of id id.

enableElements #

  • Java: void enableElements(String[] ids)
  • Node.js: enableElements(ids[,callback])
  • Perl: enableElements(@ids)
  • Python: enableElements(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: disableElement(id)
  • Ruby: disableElement(id)

Disables element of if id.

disableElements #

  • Java: void disableElements(String[] ids)
  • Node.js: disableElements(ids[,callback])
  • Perl: disableElements(@ids)
  • Python: disableElements(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: previousSibling(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 nextSibling(String id)
  • Node.js: nextSibling(id[,callback])
  • Perl: nextSibling($id)
  • Python: nextSibling(id)
  • Ruby: nextSiblinid)

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

firstChild #

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

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

lastChild #

  • Java: String lastChild(String id)
  • Node.js: lastChild(id[,callback])
  • Perl: lastChild($id)
  • Python: lastChild(id)
  • Ruby: lastChild(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: scrollTo(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 createHTML(…) or createXML(…) 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.

Properties #

getProperty #

  • Java: String getProperty(String id, String name)
  • Node.js: getProperty(id,name[,callback])
  • Perl: getProperty($id, $name)
  • Python: getProperty(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: setProperty(id,name,value)
  • Ruby: setProperty(id,name,value)

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