API du toolkit Atlas (v0.13) #

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’éléments ((set|get)Value[s]) ;
• gérer les classes CSS ((add|remove|toggle)Class[es])) ;
• activer/désactiver des éléments ((enable|disable)Element[s]) ;
• gérer des attributs/propriétés ((get|set)(Attribute[s]|Property)).
• …

Jetez également un coup d’œil aux exemples ; 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.

Le préfixe xdh: remplace maintenant l’ancien préfixe déprécié (mais parfois encore utilisé) data-xdh-.

Les attributs xdh:onevent(s) #

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

Les valeurs de 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 xdh:onevent="Submit" sur un élément button est identique à définir xdh:onevent="click|Submit", car l’événement onclick est l’événement par défaut pour un bouton.

Avec l’attribut 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 : createHTML([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 : pushTag(tag)
• Ruby : pushTag(tag)

Créer une nouvelle balise de label tag.

popTag #

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

hold (Node.js >= 0.13.2 seulement) #

• Node.js: hold()

Lors d’un appel à une méthode dom sans callback ou avec un callback n’appelant pas de méthode dom, et que vous appeliez plus tard (de manière asynchrone) une méthode dom, l’erreur Out of frame function call! sera générée.
Pour éviter cela, appelez cette méthode hold() en cas de callback manquant, ou, dans l’autre cas, avant que le callback ne rende la main.

flush #

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

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

log #

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

Affiche le message message dans la console web.

Attributs #

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)

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 : removeAttribute(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 : setAttribute(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.

Classes #

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

Valeurs #

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

Pour un groupe de boutons radio dont l’attribut name a la même valeur, si cette valeur est donnée à l’attribut xdh:radio de l’élément dont l’identifiant est passé à la méthode getValue(s)(...), alors c’est la valeur de l’attribut value du bouton radio sélectionné qui est retournée.

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

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

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

En outre, pour les fonctions getMark[s](…), récupère la valeur de l’attribut 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 xdh:mark de son parent, ou, si cet attribut n’est pas présent pour cet élément, la valeur de l’attribut xdh:mark de son parent, et ainsi de suite…

Éléments #

enableElement #

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

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 firstChild(String id)
• Node.js : firstChild(id[,callback])
• Perl : firstChild($id)
• Python : firstChild(id)
• Ruby : firstChild(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 lastChild(String id)
• Node.js : lastChild(id[,callback])
• Perl : lastChild($id)
• Python : lastChild(id)
• Ruby : lastChild(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 : scrollTo(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 createHTML(…) ou createXML(…) 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,
• after pour mettre le code HTML après l’élément.

Propriétés #

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)

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 : setProperty(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.