API du toolkit Atlas (v0.12)
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 :
(set|get)Value[s]
) ;(add|remove|toggle)Class[es])
) ;(enable|disable)Element[s]
) ;(get|set)(Attribute[s]|Property)
).Jetez également un coup d'œil aux examples ; cela vous aidera à comprendre le fonctionnement du toolkit.
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.
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 (|
).
Les fonctions ci-dessous sont les seules qui ne sont pas membres de l'objet DOM.
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
info.q37.atlas.xdhq.XML createHTML([String rootTag])
createHTML([rootTag])
createHTML([$rootTag)]
create_HTML([rootTag])
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
void pushTag(String tag)
pushTag(tag)
pushTag($tag)
pushyag(tag)
pushTag(tag)
Créer une nouvelle balise de label tag
.
popTag
void popTag()
popTag()
popTag()
pop_tag()
popTag()
La balise parente devient la balise courante.
putAttribute
<Value> void putAttribute(String name, Value value)
putAttribute(name,value)
putAttribute($name,$value)
put_attribute(name,value)
putAttribute(name,value)
Ajoute un attribut de nom name
et de valeur value
à la balise actuelle.
putValue
<Value> void putValue(Value value )
putValue(value)
putValue($value)
put_value(value)
putValue(value)
value
devient la valeur de la balise courante.
putTagAndValue
<Value> void putTagAndValue(String tag, Value value )
putTagAndValue(tag, value)
putTagAndValue($tag, $value)
put_tag_and_value(tag, value)
putTagAndValue(tag, value)
Crée une balise de nom tag
et de valeur value
.
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
info.q37.atlas.xdhq.XML createXML(String rootTag)
createXML(rootTag)
createXML($rootTag)
create_XML(rootTag)
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.
Identique à ceux décrites dans Fonctions associées à HTML.
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 action
x
sont les actions spécifiées dans les attributs data-xdh-onevent(s)
, et les callback
x
, les callbacks qui reçoivent, dans cet ordre :
createCallback
,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.
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.
launch(createCallback,callbacks,headContent)
callbacks
doit être de la forme suivante :
{
'action1': callback1,
'action2': callback2,
'action3': callback3,
…
}
launch(\%callbacks, \&createCallback, $headContent)
callbacks
doit être de la forme suivante :
{
"action1" => \&callback1,
"action2" => \&callback2,
"action3" => \&callback3,
…
}
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.
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)
action
est 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
void broadcastAction(String action[, String id])
broadcastAction(action[,id])
broadcastAction($action[,$id])
broadcast_action(action,id="")
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
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
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
.
alert
void alert(String message)
alert(message[,callback])
alert($message)
alert(message)
alert(message)
Affiche une boite de dialogue avec le message message
.
confirm
boolean confirm(String message)
confirm(message[,callback])
confirm($message)
confirm(message)
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
void focus(String id)
focus(id[,callback])
focus($id)
focus(id)
focus(id)
Donne le focus à l'élément d'identifiant id
.
flush
void flush()
flush([callback])
flush()
flush()
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
String getAttribute(String id, String name)
getAttribute(id,name[,callback])
getAttribute($id, $name)
get_attribute(id,name)
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
void removeAttribute(String id, String name)
removeAttribute(id,name[,callback])
removeAttribute($id, $name)
remove_attribute(id,name)
removeAttribute(id,name)
Retire l'attribut de nom name
de l'élement d'identifiant id
.
setAttribute
void setAttribute(String id, String name, String value)
setAttribute(id,name,value[,callback])
setAttribute($id, $name, $value)
set_attribute(id,name,value)
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
void addClass(String id, String class)
addClass(id,class[,callback])
addClass($id, $class)
add_class(id,class)
addClass(id,class)
addClasses
void addClasses((Map<String,String> idsAndClasses)
addClasses(idsAndClasses[,callback])
addClasses(@idsAndClasses)
add_classes(idsAndClasses)
addClasses(idsAndClasses)
removeClass
void removeClass(String id, String class)
removeClass(id,class[,callback])
removeClass($id, $class)
remove_class(id,class)
removeClass(id,class)
removeClasses
void removeClasses((Map<String,String> idsAndClasses)
removeClasses(idsAndClasses[,callback])
removeClasses(@idsAndClasses)
remove_classes(idsAndClasses)
removeClasses(idsAndClasses)
toggleClass
void toggleClass(String id, String class)
toggleClass(id,class[,callback])
toggleClass($id, $class)
toggle_class(id,class)
toggleClass(id,class)
toggleClasses
void toggleClasses((Map<String,String> idsAndClasses)
toggleClasses(idsAndClasses[,callback])
toggleClasses(@idsAndClasses)
toggle_classes(idsAndClasses)
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
String getValue(String id)
getValue(id[,callback])
getValue($id)
get_value(id)
getValue(id)
getValues
String[] getValues(String[] ids)
getValues(ids[,callback])
getValues(@Ids)
get_values(ids)
getValues(ids)
setValue
void setValue(String id, String value)
setValue(id,value[,callback])
setValue($id, $value)
set_value(id,value)
setValue(id,value)
setValues
void setValues((Map<String,String> idsAndValues)
setValues(idsAndValues[,callback])
setValues(@idsAndValues)
set_values(idsAndValues)
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
void enableElement(String id)
enableElement(id[,callback])
enableElement($id)
enable_element(id)
enableElement(id)
Active l'élément d'identifiant id
.
enableElements
void enableElements(String[] ids)
enableElements(ids[,callback])
enableElements(@ids)
enable_elements(ids)
enableElements(ids)
Active les éléments d'identifiants ids
(tableau de chaînes de caractères).
disableElement
void disableElements(String id)
disableElement(id[,callback])
disableElement($id)
disable_element(id)
disableElement(id)
Désactive l'élément d'identifiant id
.
disableElements
void disableElements(String[] ids)
disableElements(ids[,callback])
disableElements(@ids)
disable_elements(ids)
disableElements(ids)
Désactive les éléments d'identifiants ids
(tableau de chaînes de caractères).
parent
String parent(String id)
parent(id[,callback])
parent($id)
parent(id)
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
String previousSibling(String id)
previousSibling(id[,callback])
previousSibling($id)
previous_sibling(id)
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
String Sibling(String id)
Sibling(id[,callback])
Sibling($id)
_sibling(id)
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
String Child(String id)
Child(id[,callback])
Child($id)
_child(id)
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
String Child(String id)
Child(id[,callback])
Child($id)
_child(id)
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
void scrollTo(String id)
scrollTo(id[,callback])
scrollTo($id)
scroll_to(id)
scrollTo(id)
Positionne l'élément d'identifiant id
dans la zone visible de la fenêtre du navigateur.
before
, begin
, inner
, end
, after
)void <function>(String id, (String|info.q37.xdhq.XML) htmlOrXML, String xslFilename)
<function>(id,htmlOrXML[[,xslFilename][,callback]])
<function>($id,$htmlOrXML,$xslFilename)
<function>(id,htmlOrXML,xslFilename)
<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,after
pour mettre le code HTML après l'élément.Property
getProperty
String getProperty(String id, String name)
getProperty(id,name[,callback])
getProperty($id, $name)
get_property(id,name)
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
void setProperty(String id, String name, String value)
setProperty(id,name,value[,callback])
setProperty($id, $name, $value)
set_property(id,name,value)
setProperty(id,name,value)
Définit value
comme valeur de la propriété nommée name
de l'élément d'identifiant id
.