3 La structure du document

Le langage XForms 1.0 est une application XML [XML 1.0] conçue pour être utilisée dans d'autres vocabulaires XML, notamment dans une version future de XHTML [XHTML 1.0]. XForms est toujours tributaire d'un tel langage hôte. Ce chapitre présente les structures de XForms qui permettent de l'utiliser avec d'autres types de documents.

3.1 L'espace de nommage XForms

L'espace de nommage XForms a l'adresse URI suivante : http://www.w3.org/2002/xforms.

Les processeurs XForms doivent utiliser le mécanisme des espaces de nommage XML [XML Names] pour reconnaître les éléments et attributs de cet espace de nommage.

3.2 Les collections des attributs de base de XForms

3.2.1 Les attributs communs

La collection des attributs communs s'applique à chaque élément dans l'espace de nommage XForms.

anyAttribute

Tous les éléments XForms admettent des attributs étrangers.

Le langage hôte doit autoriser un attribut de type xsd:ID sur chaque élément XForms.

3.2.2 Les attributs de liaison

La collection des attributs de liaison s'applique aux éléments XForms qui comprennent un lien vers une ressource distante.

src

L'attribut src assigne une adresse URI à charger automatiquement.

Remarque :

Dans la mesure où les adresses URI des attributs de liaison sont définies en fonction du type de donnée xsd:anyURI du schéma XML, les mêmes avantages en terme d'internationalisation et avertissements concernant les caractères blancs s'appliquent comme expliqué dans [XML Schema part 2].

Le comportement des adresses URI relatives dans les liens est déterminé par le langage hôte, même si un traitement [XML Base] est fortement recommandé.

Remarque :

Les groupes de travail XForms et HTML sont à la recherche d'une méthode de description des structures de lien.

3.2.3 Les attributs de liaison de nœud simple

Les attributs suivants définissent une liaison entre une commande de formulaire, ou une action, et un nœud de données d'instance défini par une expression XPath.

ref

Une expression de liaison d'interprétation XPath. Cet attribut n'est pas significatif lorsqu'un attribut bind est présent.

model

Un sélecteur de modèle XForms. Il indique l'ID d'un modèle XForms à associer à cet élément de liaison. Cet attribut n'est pas significatif pour l'élément de liaison courant lorsqu'un attribut bind est présent. Les règles de détermination du modèle XForms contextuel se trouvent à 7.4 Le contexte d'évaluation.

bind

Appelle un élément bind.

L'un des deux attributs ref ou bien bind est exigé. Lorsqu'on utilise l'attribut bind, le nœud est déterminé par l'élément bind appelé.

Une exception est générée (cf. 4.5.1 L'événement xforms-binding-exception) si le processeur XForms rencontre un attribut model (resp. bind) dont la valeur de type IDREF ne correspond pas à un attribut id d'élément model (resp. bind).

Règle du premier nœud : Lorsqu'un attribut de liaison de nœud simple sélectionne un ensemble de nœuds de dimension supérieure à 1, c'est le premier nœud de cet ensemble, dans l'ordre du document, qui est utilisé.

3.2.4 Les attributs de liaison d'ensemble de nœuds

Les attributs suivants définissent une liaison entre une commande de formulaire, ou une action, et un ensemble de nœuds défini par une expression XPath.

nodeset

Une expression de liaison d'interprétation XPath. Cet attribut n'est pas significatif lorsqu'un attribut bind est présent.

model

Un sélecteur de modèle XForms. Il indique la valeur de type ID d'un modèle XForms à associer à cet élément de liaison. Cet attribut n'est pas significatif pour l'élément de liaison courant lorsqu'un attribut bind est présent. Les règles de détermination du modèle XForms contextuel se trouvent à 7.4 Le contexte d'évaluation.

bind

Appelle un élément bind.

L'un des deux attributs nodeset ou bien bind est exigé. Lorsqu'on utilise l'attribut bind, l'ensemble de nœuds est déterminé par l'élément bind appelé.

Une exception est générée (cf. 4.5.1 L'événement xforms-binding-exception) si le processeur XForms rencontre un attribut model (resp. bind dont la valeur de type IDREF ne correspond pas à un attribut id d'élément model (resp. bind).

3.2.5 Les attributs des propriétés d'élément de modèle

Cette collection contient un attribut pour chaque propriété d'élément de modèle, dont le nom correspond exactement à celui de la propriété d'élément de modèle comme définie dans 6.1 Les définitions des propriétés d'élément de modèle.

3.3 Le module Noyau de XForms

Le module Noyau de XForms définit les éléments de structure fondamentaux de XForms, et il est prévu pour être inclus dans un document conteneur. Les éléments et attributs inclus dans ce module sont :

Élément Attributs Modèle de contenu minimal
model Communs, Événements, functions (QNameList), schema (liste de xsd:anyURI) (instance|xsd:schema|submission|bind|Action)*
instance Communs, Liaison (ANY)
submission Communs, ref (expression-de-liaison), bind (xsd:IDREF), action (xsd:anyURI), method ("post"|"get"|"put"|"form-data-post"|"urlencoded-post"|qname-but-not-ncname), version (xsd:NMTOKEN), indent (xsd:boolean), mediatype (xsd:string), encoding (xsd:string), omit-xml-declaration (xsd:boolean), standalone (xsd:boolean), cdata-section-elements (QNameList), replace ("all"|"instance"|"none"|qname-but-not-ncname), instance (xsd:IDREF), separator (';' | '&'), includenamespaceprefixes (xsd:NMTOKENS) Action*
bind Communs, Propriétés d'élément de modèle, nodeset (expression-de-liaison-de-modèle) (bind)*

Les éléments définis dans le module Action de XForm, quand il est inclus, sont aussi permis dans le modèle de contenu des éléments model et submission, comme indiqué ci-dessus.

Dans le document conteneur, ces éléments de structure ne sont normalement pas restitués.

Le processeur XForms doit ignorer tous les attributs non reconnus issus d'un espace de nommage étranger, et il doit en traiter les éléments conformément aux règles dans 3.4 Le module MustUnderstand de XForms.

Remarquez que la présence des éléments issus d'un espace de nommage étranger est soumise à la définition du profil du document conteneur.

3.3.1 L'élément model

Cet élément représente une définition de formulaire et il sert de conteneur aux éléments qui définissent le modèle XForms. Il n'y aucune restriction sur le nombre d'éléments model pouvant exister dans un document conteneur.

Attributs communs : Communs, Événements

Les attributs de XML Events sont admis sur cet élément afin de faciliter la création d'observateurs. Cet élément n'est pas une action XForms et il n'a aucun comportement prédéfini vis-à-vis des événements.

Attributs particuliers :

functions

Liste optionnelle des fonctions d'extension XPath (représentées par un type QNames), séparées par des espaces, requises par ce modèle XForms. On trouvera un guide d'utilisation de cet attribut dans 7.12 Les fonctions d'extension.

schema

Liste optionnelle de liens de type xsd:anyURI vers des documents de schéma XML hors de cet élément model. Le processeur XForms doit traiter tous les schémas listés par cet attribut. Dans chaque modèle XForms, une limite d'un schéma par déclaration d'espace de nommage existe, comprenant les schémas directs et ceux reliés.

Remarque :

La liste de l'attribut schema peut inclure des fragments d'adresse URI appelant des éléments situés ailleurs dans le document conteneur, par exemple, #myschema.

Cet exemple montre une utilisation simple de l'élément model, l'espace de nommage XForms étant implicite :

Example: Model
<model id="personne" schema="MySchema.xsd">
  <instance src="http://example.com/cgi-bin/get-instance" />
  ...
</model>

3.3.2 L'élément instance

Cet élément optionnel contient ou appelle les données d'instance initiales.

Attributs communs : Communs

Attributs particuliers :

Attributs de liaison

Un lien optionnel vers des données d'instance initiales définies ailleurs. Si la traversée du lien échoue, elle se traite comme une exception (cf. 4.5.2 L'événement xforms-link-exception).

Si un attribut et un contenu direct sont tous deux fournis, alors la version reliée est prioritaire comme décrit dans 4.2.1 L'événement xforms-model-construct.

Si les données d'instance initiales sont fournies par un lien, alors elles sont formées en créant un modèle de données XPath de la ressource reliée.

Remarque :

Toutes les données significatives pour le modèle de données XPath doivent être préservées au cours du traitement et de la soumission, y compris les instructions de traitement, les nœuds de commentaire et tous les caractères blancs.

Si les données d'instance initiales sont fournies par un contenu direct, alors elles sont obtenues en créant d'abord une copie disjointe du contenu direct (y compris les espaces de nommage hérités des éléments englobants) puis en créant un modèle de données XPath sur la copie disjointe. Cette copie disjointe doit se composer d'un contenu qui, s'il existait dans un document séparé, serait bien formé pour XML. Remarquez que cela restreint le contenu de l'élément instance à un seul sous-élément.

Si la création de la copie détachée des données d'instance en ligne échouait à cause d'une erreur XML, alors le traitement devrait s'interrompre avec une exception xforms-link-exception. Cela peut se produire, par exemple, si le contenu en ligne se compose de deux nœuds d'élément, ce qui aurait impliqué la création d'un document XML avec deux éléments document.

Remarque :

Dans XForms 1.1, un nouvel événement d'exception sera généré.

Remarque :

Les auteurs XForms qui ont besoin de plus de contrôle sur la sérialisation des nœuds d'espace de nommage peuvent utiliser l'attribut includenamespaceprefixes sur l'élément submission.

3.3.3 L'élément submission

Cet élément représente les instructions déclaratives sur ce qu'il faut soumettre, et comment. Les détails concernant le traitement de la soumission sont décrits dans 11 La soumission.

Attributs communs : Communs

Attributs particuliers :

bind

L'appel optionnel d'un élément bind. Quand il est présent, l'appel de liaison sur cet attribut est employée de préférence à tout appel de liaison d'un attribut ref.

ref

Une expression de liaison sélectrice optionnelle permettant la soumission d'une partie des données d'instance. Le nœud sélectionné et tous ses descendants sont sélectionnés pour la soumission. La valeur implicite est "/".

action

Une adresse URI obligatoire à laquelle soumettre les données d'instance. Le comportement des adresses URI relatives dans les liens est déterminé par le langage hôte, même si un traitement [XML Base] est fortement recommandé.

method

Un attribut obligatoire indiquant le protocole à utiliser pour transmettre les données d'instance sérialisées. Aucune valeur par défaut.

version

Un attribut optionnel indiquant la version de XML à sérialiser.

indent

Un attribut optionnel indiquant si le sérialiseur doit ajouter des nœuds de caractères blancs supplémentaires pour la lisibilité.

mediatype

Un attribut optionnel indiquant le type de média de la sérialisation d'instance XML. Les auteurs devraient s'assurer que le type indiqué est compatible avec application/xml.

encoding

Un attribut optionnel indiquant un codage pour la sérialisation.

omit-xml-declaration

Un attribut optionnel indiquant s'il faut omettre la déclaration XML sur les données d'instance sérialisées.

standalone

Un attribut optionnel indiquant s'il faut inclure une déclaration standalone dans l'instance XML sérialisée.

cdata-section-elements

Un attribut optionnel indiquant les noms d'élément à sérialiser avec un type CDATA.

replace

Un attribut optionnel indiquant comment les informations renvoyées après la soumission devraient s'appliquer. En l'absence de cet attribut, la valeur "all" est supposée.

instance

Attribut optionnel indiquant l'instance à remplacer lorsque l'attribut replace vaut "instance". Si l'attribut est absent, alors l'instance implicite est celle qui contient les données de soumission. Il se produit une exception xforms-binding-exception si cet attribut n'indique pas une instance du même modèle que celui de la soumission.

separator

Un attribut optionnel indiquant le caractère de séparation entre les couples nom-valeur dans le codage URL. La valeur par défaut est ";".

includenamespaceprefixes

Un attribut optionnel permettant le contrôle de la sérialisation des espaces de nommage. Quand il est absent, tous les nœuds d'espace de nommage présents dans les données d'instance sont pris en compte pour la sérialisation. Quand il est présent, il définit la liste des préfixes d'espace de nommage à prendre en compte pour la sérialisation en plus de ceux visiblement utilisés. Conformément à la recommandation [Exc-C14N], la valeur spéciale "#default" indique l'espace de nommage par défaut.

Les exemples suivants montrent comment les diverses options sur l'élément submission peuvent affecter la sérialisation application/xml. Soit le fragment XForms suivant :

<xforms:model xmlns:xforms="http://www.w3.org/2002/xforms"
              xmlns:my="http://ns.example.org/2003">
  <xforms:instance>
    <qname xmlns="">my:exemple</qname>
  </xforms:instance>
  <xforms:submission method="post" action="..."/>
</xforms:model>

Remarquez l'absence de l'attribut includenamespaceprefixes entraîne la sérialisation de tous les nœuds d'espace de nommage, ce qui donne les données d'instance sérialisées suivantes :

<qname xmlns:xforms="http://www.w3.org/2002/xforms"
       xmlns:my="http://ns.example.org/2003">my:exemple</qname>

En particulier, remarquez que l'espace de nommage XForms a été sérialisé. Dans cet exemple, pour empêcher d'inclure l'espace de nommage XForms, superflu, et conserver le préfixe nécessaire my (de l'espace de nommage de l'utilisateur), il faudra ajouter la déclaration includenamespaceprefixes="my" à l'élément submission. Quand cet attribut est présent, l'auteur a la charge de lister tous les préfixes d'espace de nommage qui ne sont pas visiblement utilisés par les données d'instance soumises.

Les attributs suivants correspondent (en ce qui concerne l'orthographe, le traitement et les valeurs implicites) à ceux de l'élément output de [XSLT 1.0], hormis l'utilisation de xsd:boolean pour remplacer "yes"|"no" :

  • version
  • indent
  • encoding
  • omit-xml-declaration
  • cdata-section-elements

Remarque :

Les attributs XSLT suivants n'ont pas d'équivalents dans XForms :

  • doctype-system
  • doctype-public

Les éléments définis dans le module des actions de XForms, lorsque celui-ci est inclus, sont aussi admis dans le modèle de contenu de l'élément submission.

3.3.4 L'élément bind

L'élément bind sélectionne un ensemble de nœuds à partir des données d'instance avec une expression de liaison de modèle dans l'attribut nodeset. Les autres attributs de l'élément bind codent les propriétés d'élément de modèle à appliquer à chaque nœud dans l'ensemble de nœuds. Lorsque l'élément bind a un attribut de type xsd:ID, il associe alors cet identificateur à l'ensemble de nœuds sélectionné.

Attributs communs : Communs, Propriétés d'élément de modèle

Attributs particuliers :

nodeset

Une expression de liaison de modèle qui sélectionne l'ensemble des nœuds sur lequel cet élément bind agit, comme défini dans le chapitre 7.5.2 Les expressions de liaison de modèle.

Lorsque d'autres nœuds sont ajoutés par le biais d'une action insert, ces nœuds sont inclus dans tous les ensembles de nœuds filtrés par l'expression de liaison (cf. l'action insert dans le chapitre 9.3.5 L'élément insert.

Voir le chapitre 7.4 Le contexte d'évaluation pour des précisions sur la manière dont une liaison affecte le contexte d'évaluation.

3.4 Le module MustUnderstand de XForms

Certains éléments, tel que l'élément extension ou les éléments avec des espaces de nommage étrangers définis dans un langage hôte, peuvent être indispensables au fonctionnement d'un formulaire particulier. Pour l'indiquer, le module MustUnderstand définit un seul attribut qu'on peut utiliser sur n'importe quel élément.

Élément Attributs Modèle de contenu minimal
ANY xforms:mustUnderstand (xsd:boolean) n/a

Si un élément est marqué mustUnderstand="true" et que le processeur XForms ne dispose pas d'une implémentation pour le traiter, il s'agit alors d'une erreur terminale qui doit être signalée à l'utilisateur.

3.5 Le module Extension de XForms

Un langage hôte peut inclure un code XForms de plusieurs façons : une approche utilise exclusivement un traitement bien formé au détriment de la validation ; une autre utilise une validation stricte (par exemple, le langage XHTML 1.0) selon laquelle seuls des éléments prédéfinis sont permis ; une autre approche commune admet un contenu irrégulier dans quelques emplacements sélectionnés. Un langage hôte qui emprunte cette voie peut se servir du module Extension.

Élément Attributs Modèle de contenu minimal
extension Communs ANY

3.5.1 L'élément extension

L'élément optionnel extension est un conteneur pour les éléments d'extension propres à une application issus de tout espace de nommage autre que l'espace de nommage XForms. La présente spécification ne définit pas le traitement de cet élément.

Attributs communs : Communs

Par exemple, on pourrait joindre des métadonnées RDF à une commande de formulaire particulière de la façon suivante :

<input ref="dataset/user/email" id="email-input">
  <label>Saisissez votre adresse de courrier électronique</label>
  <extension>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="#email-input">
        <my:carnetAdresses>personnel</my:carnetAdresses>
      </rdf:Description>
    </rdf:RDF>
  </extension>
</input>