The API (v0.5)

Structure of an application

Although dedicated to the design of web front-ends, 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 application 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)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)),
  • ...

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 the concerned element, the callback registered with the launch(...) (Node.js API) function and associate with the tag of value action will be called, or the handle(...) callback (other APIs) will be called with appropriate arguments, under other 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", 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 attribute

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 content (see the launch function) as indicated in the widget's 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 $(...).name(...) 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 (\(, \), \|).

Global functions (not members of the DOM object)

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

createXML

  • Java: info.q37.atlas.xdhq.XML createXML(String rootTag),
  • Node.js: createXML(rootTag),
  • PHP: createXML(string $rootTag)
  • Python: createXML(rootTag),

Returns an object which can be used to create the XML data for below setLayoutXSL(...) method. rootTag will be the label ot ths root tag of the XML tree.

pushTag

  • Java: void pushTag(String tag),
  • Node.js: pushTag(tag),
  • PHP: pushTag(string $tag).
  • Python: pushTag(tag),

Create a new tag of label tag.

popTag

  • Java: void popTag(),
  • Node.js: popTag(),
  • PHP: popTag().
  • Python: popTag(),

The current tag becomes the parent of the current one.

setAttribute

  • Java: <Value> void setAttribute(String name, Value value),
  • Node.js: setAttribute(name,value),
  • PHP: setAttribute(string $name, $value).
  • Python: setAttribute(name,value),

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

setValue

  • Java: <Value> void setValue(Value value ),
  • Node.js: setValue(value),
  • PHP: setValue($value).
  • Python: setValue(value),

Set value as value for the current tag.

launch

This function launches the event loop of the application.

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

void launch(String newSessionAction, String headContent)

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

newSessionAction is the label of the action launched on a new session.

headContent is added to the head section of the application's main page. Must be given but can be empty.

Node.js

launch(createCallback,newSessionAction,callbacks,headContent)

createCallback is called for each new session. This callback must return an instantiation of the DOM class, or a subclass of it.

newSessionAction is one of the tag from the callbacks parameter, whose callback will be called for each new connection.

callbacks contains for each action specified in event related attributes (data-xdh-onevent(s)) the callback to be called. It must be of following form:

{
    'tag1': callback1,
    'tag2': callback2,
    'tag3': callback3,
    ...
}

tagx are the action specified in the data-xdh-onevent(s) attributes, and callbackx, callbacks which receive as first parameter the object returned by createCallback, and, as second parameter, the id of the element which receives the event.

headContent is added to the head section of the application's main page.

PHP

function launch(string $newSessionAction, newObjectCallback, string $headContent)

This is a static method of the Atlas class.

newSessionAction is the label of the action returned on each new session.

newObjectCallback is the name, as a string, of the function which must be called to get an object dedicated to a new session.

headContent is added to the head section of the application's main page.

Python

launch(newSessionAction,callbacks,createCallback=lambda:None,headContent="")

newSessionAction is the label of the action launched on a new session.

callbacks contains for each action specified in event related attributes (data-xdh-onevent(s)) the callback to be called. It must be of following form:

{
    'tag1': callback1,
    'tag2': callback2,
    'tag3': callback3,
    ...
}

tagx are the action specified in the data-xdh-onevent(s) attributes, and callbackx, callbacks which receive as first parameter the object returned by createCallback, and, as second parameter, the DOM object which is described below, and as third parameter, the id of the element which receives the event.

headContent is added to the head section of the application's main page. Must be given but can be empty.

new is a callback which returns an object which defines the below described handle method, and is called for each new session.

handle

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

For Node.js and Python, 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 as for most of the other languages.

  • Java: public void info.q37.atlas.Atlas.handle(q37.info.atlas.DOM dom, String action, String id),
  • PHP: handle($dom, $action, $id)

This function when an action has to be handled, so you have to implement it. You get :

  • dom, to manipulate the DOM (which functions are described below),
  • action, which is the action value defined in the data-xdh-onevent(s) attributes for the element which receives the event, or the value of the newSessionAction parameter given to the above launch function when a new session is launched,
  • id, the id of this element.

General functions

alert

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

Displays an alert box with message as message.

confirm

  • Java: boolean confirm(String message)
  • Node.js: confirm(message[,callback])
  • PHP: confirm(string $message)
  • Python: 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])
  • PHP: focus(string $id)
  • Python: focus(id)

Gives the focus to element of id id.

setTimeout

  • Java: void setTimeout(int delay, String action)
  • Node.js: setTimeout(delay,action[,callback])
  • PHP: setTimeout(int $delay, string $action)
  • Python: setTimeout(delay,action)

Launch action after delay ms.

createElement

  • Java: String createElement(String name[, String id])
  • Node.js: createElement(name[,id][,callback])
  • PHP: createElement(string $name[, string $id])
  • Python: createElement(name[,id])

Creates an HTML element of name name. Returns (gives as parameter to the callback for the Node.js version) id, or an unique generated id if id is missing or empty.

insertChild

  • Java: void insertChild(String child, String id)
  • Node.js: insertChild(child,id[,callback])
  • PHP: insertChild(string $child, string $id)
  • Python: insertChild(child,id)

Element of id child becomes the first child of element of id id.

Attribute

getAttribute

  • Java: String getAttribute(String id, String name)
  • Node.js: getAttribute(id,name[,callback])
  • PHP: getAttribute(string $id, string $name)
  • Python: getAttribute(id,name)

Returns (gives as parameter to the 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])
  • PHP: removeAttribute(string $id, string $name)
  • Python: 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])
  • PHP: setAttribute(string $id, string $name, string $value)
  • Python: setAttribute(id,name,value)

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

Class

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',
    ...
}

PHP:

[
    "id1" => "class1",
    "id2" => "class2",
    "id3" => "class3",
    ...
]

Python:

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

addClass

  • Java: void addClass(String id, String class)
  • Node.js: addClass(id,class[,callback])
  • PHP: addClass(string $id, string $class)
  • Python: addClass(id,class)

addClasses

  • Java: void addClasses((Map<String,String> idsAndClasses)
  • Node.js: addClasses(idsAndClasses[,callback])
  • PHP: addClasses(array $idsAndClasses)
  • Python: addClasses(idsAndClasses)

removeClass

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

removeClasses

  • Java: void removeClasses((Map<String,String> idsAndClasses)
  • Node.js: removeClasses(idsAndClasses[,callback])
  • PHP: removeClasses(array $idsAndClasses)
  • Python: removeClasses(idsAndClasses)

toggleClass

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

toggleClasses

  • Java: void toggleClasses((Map<String,String> idsAndClasses)
  • Node.js: toggleClasses(idsAndClasses[,callback])
  • PHP: toggleClasses(array $idsAndClasses)
  • Python: toggleClasses(idsAndClasses)

Content

getContent

  • Java: String getContent(String id)
  • Node.js: getContent(id[,callback])
  • PHP: getContent(string $id)
  • Python: getContent(id)

Retrieve (gives as parameter to the callback for the *Node.js- zversion) the content of the element of id id.

getContents

  • Java: String[] getContents(String[] ids)
  • Node.js: getContents(ids[,callback])
  • PHP: getContents(array $ids)
  • Python: getContents(ids)

Retrieves(gives as parameter to the callback for the Node.js version) the content of the elements of ids ids in the same order.

setContent

  • Java: void setContent(String id, String content)
  • Node.js: setContent(id,value[,callback])
  • PHP: setContent(string $id, string $content)
  • Python: setContent(id,value)

Set the content of element of id id to value.

setContents

  • Java: void setContents((Map<String,String> idsAndContents)
  • Node.js: setContents(idsAndValues[,callback])
  • PHP: setContents(array $idsAndContents)
  • Python: setContents(idsAndValues)

Set the content of all element which id are in idsAndContents to corresponding content.

The idsAndContents parameter must have following form:

Java:

new HashMap<String,String>()
{{
    put("id1", "content1");
    put("id2", "content2");
    put("id3", "content3");
    ...
}

Node.js:

{
    'id1': 'content1',
    'id2': 'content2',
    'id3': 'content3',
    ...
}

PHP:

[
    "id1" => "content1",
    "id2" => "content2",
    "id3" => "content3",
    ...
]

Python:

{
    'id1': 'content1',
    'id2': 'content2',
    'id3': 'content3',
    ...
}

Element

enableElement

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

Enable element of id id.

enableElements

  • Java: void enableElements(String[] ids)
  • Node.js: enableElements(ids[,callback])
  • PHP: enableElements(array $ids)
  • Python: enableElements(ids)

Enable element of ids ids.

disableElement

  • Java: void disableElements(String[] ids)
  • Node.js: disableElement(id[,callback])
  • PHP: disableElement(string $id)
  • Python: disableElement(id)

Disable element of if id.

disableElements

  • Java: void disableElements(String[] ids)
  • Node.js: disableElements(ids[,callback])
  • PHP: disableElements(array $ids)
  • Python: disableElements(ids)

Disable element of ids ids (array of strings).

Layout

setLayout

  • Java: void setLayout(String id, String html)
  • Node.js: setLayout(id,html[,callback])
  • PHP: setLayout(string $id, string $html)
  • Python: setLayout(id,html)

Replaces the content of element with string id as id with the content of html.

If id is an empty string, the content of the entire document is replaced.

The content of html can be generated with the template engine of your choice. For XSL(T), you can used the dedicated method setLayoutXSL(...).

setLayoutXSL

  • Java: void setLayoutXSL(String id, (String|info.q37.xdhq.XML) xml, String xslFilename)
  • Node.js: setLayoutXSL(id,xml,xslFilename[,callback])
  • PHP: setLayoutXSL(string $id,$xml, string $xslFilename)
  • Python: setLayoutXSL(id,xml,xslFilename)

Replaces the content of element with string id as id with the result of the transformation of the XSL file with name xslFilename applied to the content of xml, which must a string containing valid XML, or the object returned by the createXML(...) function.

If id is an empty string, the content of the entire document is replaced by the resulting transformation.

For the Node.js version only, to allow embedded XSL (for use with RunKit), if the content of the xslFilename parameter begins with <, that its content is handled as XSL, not as a the name of the file containing XSL.

Property

getProperty

  • Java: String getProperty(String id, String name)
  • Node.js: getProperty(id,name[,callback])
  • PHP: getProperty(string $id, string $name)
  • Python: getProperty(id,name)

Returns (gives as parameter to the 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])
  • PHP: setProperty(string $id, string $name, string $value)
  • Python: setProperty(id,name,value)

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

Widget

dressWidgets

  • Java: void dressWidgets(String id)
  • Node.js: dressWidgets(id[,callback])
  • PHP: dressWidgets(string $id)
  • Python: dressWidgets(id)

Creates the widget for each elements which are children of the element of id id and which have a data-xdh-widget attribute.

If id is an empty string, the entire document is handled.