API du toolkit Atlas (v0.12)

---

Structure d'un programme

Bien que concernant des applications web, le toolkit de Atlas n'est pas basé sur un modèle architectural particulier, comme les populaires frameworks relatif au modèle MVC. Ainsi, la structure d'un programme basé sur le toolkit Atlas est plutôt simple.

launch(…) est la fonction principale. Ensuite, pour chaque action de l'utilisateur, il suffit d'effectuer les actions appropriées sur le DOM, comme :

• définir/obtenir la valeur d'élements ((set|get)Value[s]) ;
• gérer les classes CSS ((add|remove|toggle)Class[es])) ;
• activer/désactiver des élements ((enable|disable)Element[s]) ;
• gérer des attributs/propriétés ((get|set)(Attribute[s]|Property)).
• …

Jetez également un coup d'œil aux examples ; cela vous aidera à comprendre le fonctionnement du toolkit.

Le toolkit Atlas et le DOM

La plupart des fonctions liées au DOM (toutes les fonctions présentées dans cette page, sauf indication contraire) sont nommées d'après la fonction DOM correspondante, le cas échéant, ou, du moins, elles font référence aux entités DOM du même nom.

Les attributs data-xdh-onevent(s)

Un élément peut avoir un attribut data-xdh-onevent et/ou un attribut data-xdh-onevents.

Les valeurs de data-xdh-onevent sont de la forme suivante :

[event|]action

La valeur de event peut être tous les événements disponibles de JS, sans le préfixe on. Lorsque l'événement en question est lancé sur un élément, le callback enregistré avec la fonction launch(…) et associé au label action (ou le callback handle(…) pour Java) sera appelé avec les arguments appropriés.

action seul peut être spécifié, sans event, l'action est alors associée à l'événement par défaut pour l'élément concerné. Par exemple, définir data-xdh-onevent="Submit" sur un élément button est identique à définir data-xdh-onevent="click|Submit", car l'événement onclick est l'événement par défaut pour un bouton.

Avec l'attribut data-xdh-onevents (avec un s final), plusieurs actions sur un élément peuvent être spécifiées, en encadrant chaque paire event|action avec des parenthèses (( )) et en les séparant par un pipe (|).

Fonctions globales (nom membres de l'objet DOM)

Les fonctions ci-dessous sont les seules qui ne sont pas membres de l'objet DOM.

Fonctions associées à HTML

Avec les fonctions suivantes, on peut construire un arbre HTML à utiliser avec les méthodes before, begin, inner, end et after décrites ci-dessous.

createHTML

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

Retourne un objet qui peut être utilisé pour créer les données HTML pour les fonctions before, begin, inner, end et after ci-dessous. rootTag sera l'étiquette de la balise racine de l'arbre HTML ; si elle est manquante, il n'y aura pas de balise racine.

Les fonctions suivantes font partie de cet objet.

pushTag

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

Créer une nouvelle balise de label tag.

popTag

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

La balise parente devient la balise courante.

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)

Ajoute un attribut de nom name et de valeur value à la balise actuelle.

putValue

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

value devient la valeur de la balise courante.

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)

Crée une balise de nom tag et de valeur value.

Fonctions associées au XML

Avec les fonctions suivantes, on peut construire un arbre XML qui peut être transformé en HTML en utilisant un fichier XSL avec les méthodes before, begin, inner, end et after dédiées décrites plus bas.

createXML

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

Renvoie un objet qui peut être utilisé pour créer les données XML pour les méthodes before, begin, inner, end et after ci-dessous. rootTag sera le label de la balise racine de l'arbre XML. Les fonctions suivantes font partie de cet objet.

Autre méthodes

Identique à ceux décrites dans Fonctions associées à HTML.

Autres

launch

Cette fonction lance la boucle événementielle du programme. Elle comporte un paramètre optionnel headContent dont le contenu est placé dans la section head de la page HTML principale du programme.

callbacks (qui n'existe pas pour Java) est décrit ci-dessous pour chaque langage et a le contenu suivant. Les actionx sont les actions spécifiées dans les attributs data-xdh-onevent(s), et les callbackx, les callbacks qui reçoivent, dans cet ordre :

• l'objet renvoyé par createCallback,
• un objet DOM (sauf pour Node.js, pour lequel cet objet est fourni par le paramètre ci-dessus),
• l'identifiant de l'élément qui reçoit l'événement,
• le label de l'action.

Il doit exister dans callbacks une entrée avec une chaîne vide comme clé ; le callback correspondant sera appelé à chaque nouvelle session.

Dans certains exemples, des paramètres supplémentaires sont donnés à cette fonction. Pour vos propres développements, vous n'avez pas besoin de fournir ces paramètres supplémentaires.

Java

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

callback est appelé à chaque nouvelle session, et doit renvoyer un objet qui met en œuvre la méthode handle donnée ci-dessous.

Node.js

launch(createCallback,callbacks,headContent)

callbacks doit être de la forme suivante :

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

Perl

launch(\%callbacks, \&createCallback, $headContent)

callbacks doit être de la forme suivante :

{
    "action1" => \&callback1,
    "action2" => \&callback2,
    "action3" => \&callback3,
    …
}

Python

launch(callbacks,createCallback=None,headContent="")

callbacks doit être de la forme suivante :

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

Si le paramètre createCallback de la fonction launch(…) est égal à ou retourne None, le premier paramètre reçu par les callbacks est l'objet DOM, le second, l'identifiant de l'élément qui reçoit l'événement, et le troisième, le label de l'action.

Ruby

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

callbacks doit être de la forme suivante :

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

handle (Java)

Avec ce callback, vous implémentez la façon dont le programme réagit aux différentes actions.

Pour les autres langages, vous devez définir un callback pour chaque action et les donner à la fonction launch décrite ci-dessus, ce qui signifie qu'il n'y a pas de callback commun à toutes les actions.

@Override public void info.q37.atlas.Atlas.handle(String action, String id)

• actionest le libellé de l'action définie dans les attributs data-xdh-onevent(s) pour l'élément qui reçoit l'événement ;
• id est l'identifiant de cet élément.

Il y a également un objet public nommé dom de type q37.info.atlas.DOM, hérité de info.q37.atlas.Atlas, dont les méthodes sont décrites ci-dessous.

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="")

Envoie une action de type action et la valeur de id, (qui, par défaut, est une chaîne vide) à tous les clients. Vous devez créer un callback pour cette action, à l'instar des autres actions.

setSupplier

• Python : set_supplier(supplier)

supplier est une fonction qui est lancée avec, comme paramètre, l'URL correspondant à l'application.

supplier peut également être l'une des chaînes de caractères suivantes :

• none: rien ne se passe ;
• auto: l'interface de l'application est automatiquement affichée dans un navigateur - c'est le comportement par défaut ;
• qrcode: un code QR cliquable est affiché, qui peut être scanné par un smartphone ou une tablette pour y ouvrir l'application.

Si supplier est une fonction, elle peut retourner une valeur qui répond aux mêmes critères que le paramètre supplier ci-dessus, et qui va alors être utilisé de manière identique.

NOTA: la valeur de la variable d'environnement ATK supplante la valeur donnée en paramètre à cette fonction.

getAppURL

• Python : get_app_url(id="")

Retourne l'URL correspondant à l'application, qui, si ouverte, lancera une nouvelle session pour cette application.

Si id n'est pas vide, la fonction associée à l'action connect (qui correspond à l'action ayant pour label une chaîne vide) reçoit cette valeur dans le paramètre id.

Fonctions générales

alert

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

Affiche une boite de dialogue avec le message message.

confirm

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

Affiche une boite de dialogue de confirmation avec le message message.

La valeur retournée (le paramètre donné à callback pour la version Node.js) est true lorsque l'utilisateur clique sur le bouton OK (ou équivalent), et false lorsque l'utilisateur clique sur le bouton Annuler (ou équivalent).

focus

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

Donne le focus à l'élément d'identifiant id.

flush

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

Retourne (pour Node.js, appelle le callback) uniquement lorsque toutes les fonctions précédentes liées au DOM ont été exécutées.

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)

Retourne (donne en paramètre à callback pour la version Node.js) la valeur de l'attribut nommé name de l'élément d'identifiant 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)

Retire l'attribut de nom name de l'élement d'identifiant 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)

Définit value comme étant la valeur de l'attribut de nom name de l'élement d'identifiant id.

Class(es)

Les méthodes suivantes permettent de gérer les classes (les attributs class des balises HTML), respectivement en ajoutant (add…), supprimant (remove…) ou basculant (toggle… ; en l'ajoutant si elle n'est pas présente, sinon en la supprimant) une classe aux éléments désignés par leurs identifiants (le contenu de l'attribut id des balises HTML).

Le paramètre idsAndClasses doit être de la forme suivante :

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)

Les fonctions ci-dessous permettent de récupérer ou de définir le contenu d'élément désignés par leur identifiants.

Le paramètre idsAndValues doit être de la forme suivante :

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](…))

Identiques aux fonctions portant sur Value(s), mais avec le contenu de l'attribut data-xdh-mark.

En outre, pour les fonctions getMark[s](…), récupère la valeur de l'attribut data-xdh-mark de l'élément d'identifiant donné, ou, si cet attribut n'est pas présent pour cet élément, la valeur de l'attribut data-xdh-mark de son parent, ou, si cet attribut n'est pas présent pour cet élément, la valeur de l'attribut data-xdh-mark de son parent, et ainsi de suite…

Element

enableElement

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

Active l'élément d'identifiant id.

enableElements

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

Active les éléments d'identifiants ids (tableau de chaînes de caractères).

disableElement

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

Désactive l'élément d'identifiant id.

disableElements

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

Désactive les éléments d'identifiants ids (tableau de chaînes de caractères).

parent

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

Retourne l'identifiant du parent de l'élément d'identifiant id, ou une chaîne vide si cet élément n'existe pas.

previousSibling

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

Retourne l'élément précédent celui d'identifiant id, ou une chaîne vide si un tel élément n'existe pas.

nextSibling

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

Retourne l'élément suivant celui d'identifiant id, ou une chaîne vide si un tel élément n'existe pas.

firstChild

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

Retourne le premier élément enfant de l'élément d'identifiant id, ou une chaîne vide si un tel élément n'existe pas.

lastChild

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

Retourne le dernier élément enfant de l'élément d'identifiant id, ou une chaîne vide si un tel élément n'existe pas.

scrollTo

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

Positionne l'élément d'identifiant id dans la zone visible de la fenêtre du navigateur.

HTML, ou 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 peut être une chaîne de caractères, éventuellement vide, ou un objet créé par les fonctions create[_]HTML(…) ou create[_]XML(…) ci-dessus.

si xslFilename est absent, htmlOrXML doit être du HTML, sinon, ce doit être du XML, qui est transformé en HTML en appliquant le contenu du fichier spécifié dans xslFilename.

Le code HTML est appliqué à l'élément d'identifiant id en fonction de <function>, qui peut être :

• before pour mettre le code HTML avant l'élément,
• begin pour mettre le code HTML comme premier enfant de l'élément,
• inner pour remplacer le contenu de l'élément par le code HTML,
• end pour mettre le code HTML comme dernier enfant de l'élément,
• afterpour mettre le code HTML après l'élément.

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)

Retourne (donne comme paramètre à callback pour la version Node.js) la valeur de la propriété nommée name de l'élément d'identifiant 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)

Définit value comme valeur de la propriété nommée name de l'élément d'identifiant id.