10 Les actions XForms

Ce chapitre définit un jeu d'actions commun, fondé sur les événements XML [XML Events], qui peut être invoqué en réponse à des événements.

Remarque :

Le langage XForms ne définit, par lui-même, aucune méthode de gestion d'événement fondée sur des scripts. La définition de telles facilités est du ressort du langage hôte.

10.1 Le module Action de XForms

Toutes les commandes de formulaire définies dans la présente spécification possèdent un jeu de comportements communs qui encourage une cohérence de la création comme de l'aspect et de la convivialité des applications fondées sur XForms. Cette cohérence est le fruit de l'utilisation d'un ensemble de comportements commun par les diverses commandes de formulaire. En conjonction avec le mécanisme de liaison d'événement apporté par les événements XML, ces gestionnaires offrent aux auteurs de formulaires des moyens flexibles pour définir le traitement des événements aux points appropriés dans l'interface d'utilisateur XForms. Les actions XForms sont des gestionnaires d'événement XForms déclaratifs qui capturent une sémantique de niveau supérieur. Elles améliorent, par conséquent, de manière significative l'accessibilité des applications fondées sur XForms, en comparaison avec les technologies Web précédentes qui s'appuyaient exclusivement sur des scripts.

Les éléments et attributs compris dans ce module sont les suivants :

Élément Attributs Modèle de contenu minimal
action Communs, Événements (Action)+
dispatch Communs, Événements, name (xsd:NMTOKEN), target (xsd:IDREF), bubbles (xsd:boolean), cancelable (xsd:boolean) EMPTY
rebuild Communs, Événements, model (xsd:IDREF) EMPTY
recalculate Communs, Événements, model (xsd:IDREF) EMPTY
revalidate Communs, Événements, model (xsd:IDREF) EMPTY
refresh Communs, Événements, model (xsd:IDREF) EMPTY
setfocus Communs, Événements, control (xsd:IDREF) EMPTY
load Communs, Événements, Liaison de nœud simple (optionnel), resource (xsd:anyURI), show ("new" | "replace") EMPTY
setvalue Communs, Événements, Liaison de nœud simple, value (expression-XPath) PCDATA
send Communs, Événements, submission (xsd:IDREF) EMPTY
reset Communs, Événements, model (xsd:IDREF) EMPTY
message Communs, Événements, Liaison de nœud simple (optionnel), Liaison, level ("ephemeral" | "modeless" | "modal") (PCDATA|Direct d'I.U.)*

Cf. également : 9.2.3 L'élément toggle, 9.3.5 L'élément insert, 9.3.6 L'élément delete et 9.3.7 L'élément setindex.

Ce module définit également le jeu de contenu Action qui inclut les éléments suivants (parmi ceux-ci, l'élément toggle provient du module Commutation de XForms et les éléments insert, delete et setindex proviennent du module Répétition de XForms) :

(action|dispatch|rebuild|refresh|recalculate|revalidate|setfocus|
 load|setvalue|send|reset|message|toggle|insert|delete|setindex)*

En outre, ce module définit le groupe d'attributs Événements XML qui comprend tous les attributs globaux définis dans la spécification ([XML Events]).

L'exemple suivant montre comment utiliser les événements :

Exemple : Syntaxe d'une action
<xforms:trigger>
  <xforms:label>Réinitialiser</xforms:label>
  <xforms:reset ev:event="DOMActivate" model="ce-modele"/>
</xforms:trigger>

Cet exemple reproduit le comportement de la commande de réinitialisation HTML, que la présente spécification ne définit pas comme étant une commande de formulaire indépendante.

Pour chaque action XForms intégrée, le chapitre liste les caractéristiques suivantes :

Nom
Attributs communs
Attributs spéciaux
Description du comportement

Tous les éléments définis dans ce chapitre admettent explicitement les attributs globaux de l'espace de nommage de la spécification des événements XML et appliquent le traitement défini dans celle-ci dans la section 2.3 [XML Events].

10.1.1 L'élément action

L'action action permet de regrouper plusieurs actions.

Cette action détermine l'invocation des sous-actions dans l'ordre indiqué dans le document.

Lorsqu'on utilise l'élément action pour regrouper des actions, il faut faire attention à lister l'événement sur l'élément action plutôt que sur les actions qui y sont contenues.

Attributs communs : Communs, Événements

Exemple : Regrouper des actions
<trigger>
  <label>Cliquez-moi</label>
  <action ev:event="DOMActivate">
    <reset model="ce-modele"/>
    <setvalue ref="."/>
  </action>
</trigger>

Notez que, dans l'exemple ci-dessus, la déclaration ev:event="DOMActivate" apparaît sur l'élément action. Le placement de cette déclaration sur l'une, ou l'autre, ou sur les deux actions contenues ne produira aucun effet, parce que cet exemple est régi par l'action implicite des attributs observer et handler [XML Events] attributes Comme défini dans la spécification des événements XML, si les attributs observer et handler sont tous deux omis, alors c'est le parent qui est l'observateur. De ce fait, placer une déclaration ev:event="DOMActivate" sur les enfants de l'élément action va faire que l'élément action devienne l'observateur des événements individuels. Par conséquent, ces actions ne seront jamais déclenchées puisque les événements arriveront sur l'élément trigger, et non sur l'élément action.

Les mises à jour différées : Beaucoup d'actions XForms ont un effet différé sur les données d'instance lorsqu'elles sont définies comme sous-éléments d'un élément action.

Les implémentations sont libres de suivre n'importe quelle stratégie pour accomplir des mises à jours différées, mais le résultat final doit être le suivant : les changements effectués sur des données d'instance par un ensemble d'actions entraînent ni reconstruction des dépendances ni recalcul ni revalidation ni raffraîchissement des commandes de formulaires tant que le gestionnaire d'action le plus externe n'a pas terminé comme décrit ici. On peut voir chaque gestionnaire d'action le plus externe comme brandissant un ensemble de drapeaux booléens valant initialement "false", afin d'indiquer si chacune des actions rebuild, recalculate, revalidate et refresh est nécessaire pour achever le traitement du gestionnaire d'action externe en question.

Les actions qui invoquent directement une action rebuild, recalculate, revalidate ou refresh prennent effet immédiatement et neutralisent le drapeau correspondant. Les actions XForms dans cette catégorie sont :

rebuild
recalculate
revalidate
refresh

Les actions qui changent la structure d'arbre des données d'instance aboutissent à placer tous les quatres drapeaux sur "true". Les actions XForms dans cette catégorie sont :

insert
delete

Les actions qui ne changent que la valeur d'un nœud d'instance aboutissent à placer les drapeaux des actions recalculate, revalidate et refresh sur "true", sans changement sur le drapeau de l'action rebuild. Les actions dans cette catégorie sont :

setvalue

Enfin, l'action reset prend effet immédiatement et neutralise tous les drapeaux.

10.1.2 L'élément dispatch

Cette action distribue un événement XForms à un élément particulier identifié par l'attribut target. Deux types d'événement peuvent être distribués :

  1. Les événements XForms prédéfinis (c'est-à-dire xforms-nom_événement), auquel cas les attributs bubbles et cancelable sont ignorés et la sémantique normale définie dans 4 Le modèle de traitement s'applique ;

  2. Un événement créé par l'auteur XForms sans sémantique XForms prédéfinie et qui, de ce fait, n'est pas géré par défaut par le processeur XForms.

Attributs communs : Communs, Événements

Attributs spéciaux :

name

Le nom obligatoire de l'événement à distribuer.

target

La référence obligatoire de la cible de l'événement.

bubbles

Un booléen optionnel indiquant si cet événement bouillonne, comme défini dans la recommandation [DOM2 Events]. La valeur par défaut dépend de la définition d'un événement personnalisé. Cet attribut est sans effet pour les événements prédéfinis.

cancelable

Un booléen optionnel indiquant si cet événement s'annule, comme défini dans la recommandation [DOM2 Events]. La valeur par défaut dépend de la définition d'un événement personnalisé. Cet attribut est sans effet pour les événements prédéfinis.

10.1.3 L'élément rebuild

Cette action déclenche le traitement de l'événement xforms-rebuild, en court-circuitant le flux d'événement normal. Elle entraîne le processeur XForms à reconstruire toutes les structures de données internes utilisées pour le suivi des dépendances de calcul entre les nœuds de donnée d'instance (cf. 4.3.7 L'événement xforms-rebuild).

Attributs communs : Communs, Événements

Attributs spéciaux :

model

La valeur obligatoire de type IDREF du modèle à traiter.

Un sélecteur de modèle XForms optionnel, comme défini dans la section 3.2.3 Les attributs de liaison de nœud simple.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.4 L'élément recalculate

Cette action déclenche le traitement de l'événement xforms-recalculate, en court-circuitant le flux d'événement normal. Par conséquent, les nœuds de donnée d'instance dont les valeurs ont besoin d'être recalculées sont mis à jour comme indiqué dans le modèle de traitement (cf. 4.3.6 L'événement xforms-recalculate).

Attributs communs : Communs, Événements

Attributs spéciaux :

model

La valeur obligatoire de type IDREF du modèle à traiter.

Un sélecteur de modèle XForms optionnel, comme défini dans la section 3.2.3 Les attributs de liaison de nœud simple.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.5 L'élément revalidate

Cette action déclenche le traitement de l'événement xforms-revalidate, en court-circuitant le flux d'événement normal. Elle entraîne la revalidation des données d'instance comme indiqué dans le modèle de traitement (cf. 4.3.5 L'événement xforms-revalidate.

Attributs communs : Communs, Événements

Attributs spéciaux :

model

La valeur obligatoire de type IDREF du modèle à traiter.

Un sélecteur de modèle XForms optionnel, comme défini dans la section 3.2.3 Les attributs de liaison de nœud simple.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.6 L'élément refresh

Cette action déclenche le traitement de l'événement xforms-refresh, en court-circuitant le flux d'événement normal. Elle entraîne le rafraîchissement de l'interface d'utilisateur XForms et la présentation mise à jour des commandes de l'interface d'utilisateur pour refléter l'état des données d'instance sous-jacentes (cf. 4.3.4 L'événement xforms-refresh.

Attributs communs : Communs, Événements

Attributs spéciaux :

model

La valeur obligatoire de type IDREF du modèle à traiter.

Un sélecteur de modèle XForms optionnel, comme défini dans la section 3.2.3 Les attributs de liaison de nœud simple.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.7 L'élément setfocus

Cette action place le focus sur la commande de formulaire identifiée par l'attribut control en distribuant un événement xforms-focus (cf. 4.3.2 L'événement xforms-focus). Cette action distribue un événement xforms-focus à l'élément identifié par l'attribut control. Remarquez que cet événement est invoqué implicitement pour mettre en œuvre des fonctionnalités d'accessibilité XForms tel que celle de l'attribut accesskey.

Attributs communs : Communs, Événements

Attributs spéciaux :

control

Une référence obligatoire à une commande de formulaire.

Le placement du focus sur une structure qui se répète le place sur l'élément de répétition représenté par l'index de répétition.

10.1.8 L'élément load

Cette action traverse le lien indiqué.

Attributs communs : Communs, Événements, Liaison de nœud simple (optionnel)

Attributs spéciaux :

resource

Un lien vers une ressource externe à charger, définie comme un lien [XLink 1.0] entre cet élément et la ressource distance désignée. On ne définit aucune valeur pour l'attribut XLink actuate puisque le contrôle de l'actuation est défini par des événements XML. La valeur de l'attribut XLink show dépend de l'attribut show. Si la traversée du lien échoue, alors elle sera traitée comme une erreur (cf. 4.5.3 L'événement xforms-link-error).

show

Un indicateur optionnel du comportement du lien. Si cet attribut est absent, la valeur implicite est "replace".

On doit recourir soit aux attributs de liaison de nœud simple, pointant vers une adresse URI dans les données d'instance, soit aux attributs de liaisons. L'action est sans effet si les deux types sont présents.

Le document (ou portion du document) atteint par la traversée du lien est l'objet des traitements suivants selon les valeurs possibles de l'attribut show :

new

Le document est chargé dans un nouveau contexte de présentation, par exemple, une nouvelle fenêtre. Le traitement du formulaire dans la fenêtre originale se poursuit.

replace

Le document est chargé dans la fenêtre courante. Le traitement du formulaire est interrompu, exactement comme si l'utilisateur avait demandé manuellement une navigation vers un nouveau document.

10.1.9 L'élément setvalue

Cette action fixe explicitement la valeur du nœud de donnée d'instance indiqué.

Attributs communs : Communs, Événements, Liaison de nœud simple

Attributs spéciaux :

value

Une expression XPath optionnelle à évaluer, le résultat étant stocké dans le nœud de donnée d'instance sélectionné. Le contexte d'évaluation de cette expression est celui résultant de la liaison de nœud simple..

Le contenu de l'élément setvalue indique la valeur littérale à placer ; c'est une alternative à la définition d'une valeur calculée via l'attribut value. Les deux exemples suivants comparent ces approches :

Exemple : setvalue avec une expression
<setvalue bind="placer-ici" value="a/b/c"/>

Cela entraîne le placement de la valeur située à a/b/c, dans les données d'instance, sur le nœud simple sélectionné par l'élément bind avec id="placer-ici".

Exemple : setvalue avec un littéral
<setvalue bind="placer-ici">chaîne littérale</setvalue>

Cela entraîne le placement de la valeur "chaîne littérale" sur le nœud simple sélectionné par l'élément bind avec id="placer-ici".

Si ni un attribut value ni un contenu textuel ne sont présents, cela aura pour effet de fixer la valeur du nœud sélectionné à la chaîne vide (""). Si les deux sont présents, alors l'attribut value est utilisé.

Toutes les chaînes s'insèrent dans les données d'instance comme suit :

  • Les nœuds d'élément : Si l'élément a des nœuds de texte enfants, alors le premier nœude de texte est remplacé par celui correspondant à la nouvelle valeur. S'il n'y a aucun nœud de texte, alors il en sera créé un, correspondant à la nouvelle valeur, et il sera rajouté comme premier nœud enfant ;

  • Les nœuds d'attribut : La valeur de chaîne de l'attribut est remplacée par une chaîne correspondant à la nouvelle valeur ;

  • Les nœuds de texte : Le nœud de texte est remplacé par un nouveau correspondant à la nouvelle valeur ;

  • Les nœuds d'espace de nommage, d'instruction de traitement, de commentaire ou de la racine XPath : le comportement n'est pas défini.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.10 L'élément send

Cette action lance le traitement de soumission en distribuant un événement xforms-submit. Le traitement de l'événement xforms-submit est défini dans le modèle de traitement (cf. 4.3.9 L'événement xforms-submit.

Attributs communs : Communs, Événements

Attributs spéciaux :

submission

Une référence obligatoire à un élément submission.

Remarque :

Cette action XForms est un moyen commode d'exprimer ce qui suit :

<dispatch target="moninfosubmit" name="xforms-submit"/>

10.1.11 L'élément reset

Cette action lance le traitement de réinitialisation en distribuant un événement xforms-reset à l'élément model indiqué. Le traitement de l'événement xforms-reset est défini dans le modèle de traitement (cf. 4.3.8 L'événement xforms-reset.

Attributs communs : Communs, Événements

Attributs spéciaux :

model

Une sélection obligatoire des données d'instance à réinitialiser, définie dans 3.2.3 Les attributs de liaison de nœud simple.

Un sélecteur de modèle XForms optionnel, comme défini dans la section 3.2.3 Les attributs de liaison de nœud simple.

Remarque :

Si cette action est contenue dans un élément action, elle a un comportement particulier de mise à jour différée (cf. 10.1.1 L'élément action).

10.1.12 L'élément message

Cette action encapsule un message à afficher à l'utilisateur.

Attributs communs : Communs, Événements, Liaison de nœud simple (optionnel)

Attributs spéciaux :

Attributs de liaison

Un lien vers un message externe. Si la traversée du lien échoue, alors elle sera traitée comme une erreur (cf. 4.5.3 L'événement xforms-link-error).

level

Un identificateur obligatoire de niveau de message : l'un parmi ("ephemeral"|"modeless"|"modal"|QName-but-not-NCName). La présente spécification ne définit pas le comportement pour des valeurs de type QName.

Le message indiqué peut exister dans des données d'instance, dans un document distant, ou directement comme texte. Si plusieurs sources de message sont indiquées dans cet élément, l'ordre de préséance est le suivant : les attributs de liaison de nœud simple, les attributs de liaison et le texte direct.

Un navigateur graphique pourrait restituer un message "modal" comme suit :

<model>
  <message level="modal" ev:event="xforms-ready">Ce n'est pas une chignole !</message>
  ...
</model>

Une fenêtre d'alerte contenant un message d'erreur utile.

Un message "modeless" est la fondation pour l'affichage d'un message d'assistance help, qu'un navigateur graphique pourrait restituer comme suit :

<secret ref="/login/password">
  <label>Mot de passe</label>
  <help>Vous avez oublié votre mot de passe ? Appelez simplement au 01 23 45 67 89
  et ayez votre carte de crédit à portée de main.</help>
</secret>

Une commande de formulaire pour entrer un mot de passe, avec un message contextuel en-dessous donnant les instructions pour récupérer un mot de passe oublié.

Un message "ephemeral" est la fondation pour l'affichage d'un message d'indication hint, qu'un navigateur graphique pourrait restituer comme suit :

<input ref="po/adresse/rue1">
  <label>Rue</label>
  <hint>Veuillez indiquer le numéro et le nom de la rue</hint>
</input>

Une commande de formulaire d'entrée de texte d'aspect moyen avec un pointeur de souris et une infobulle en-dessous disant : 'Veuillez indiquer le numéro et le nom de la rue'

10.1.13 Les actions et les éléments insert, delete et setindex

Outre les gestionnaires d'action détaillés dans ce chapitre, XForms définit trois actions faisant partie du module Répétition de XForms : 9.3.5 L'élément insert, 9.3.6 L'élément delete, et 9.3.7 L'élément setindex.