Lisez-moi S.V.P. 

13 novembre 2000

1. Le modèle objet de document Core

Rédacteurs
Arnaud Le Hors, IBM
Gavin Nicol, Inso EPS (pour DOM niveau 1)
Lauren Wood, SoftQuad, Inc. (pour DOM niveau 1)
Mike Champion, ArborText (pour DOM niveau 1 à partir du 20 novembre 1997)
Steve Byrne, JavaSoft (pour DOM niveau 1 jusqu'au 19 novembre 1997)

Table des matières

1.1. Vue d'ensemble des interfaces DOM Core

Cette section définit un ensemble d'objets et d'interfaces pour accéder aux objets du document et les manipuler. La fonctionnalité définie dans cette section (la fonctionnalité Core) est suffisante pour permettre aux développeurs de logiciels et aux auteurs de scripts Web l'accès et la manipulation des contenus HTML, ou XML, interprétés dans des produits conformes. L'interface de programmation d'application (API) du DOM Core permet également de créer et peupler un objet Document en se servant seulement d'appels de l'interface de programmation d'application (API) DOM ; le chargement d'un objet Document et son stockage permanent sont laissés au soin du produit mettant en œuvre l'interface de programmation d'application (API) du DOM.

1.1.1. Le modèle de structure DOM

Le DOM présente les documents comme une hiérarchie d'objets Node qui mettent également en œuvre d'autres interfaces plus spécialisées. Certains types de nœud peuvent avoir des nœuds enfants de divers types, d'autres sont des nœuds terminaux qui ne peuvent avoir de descendants dans la structure du document. Pour XML et HTML, les types de nœud et leurs enfants possibles sont les suivants :

Le DOM définit également une interface NodeList pour la gestion des listes ordonnées d'objets Node, tels que les enfants d'un objet Node ou les éléments retournés par la méthode getElementsByTagName de l'interface Element, ainsi qu'une interface NamedNodeMap pour la gestion des jeux non ordonnés de nœuds référencés par leur nom d'attribut, tels que les attributs d'un objet Element. Les objets NodeList et NamedNodeMap dans le DOM sont vivants ; ce qui veut dire que les changements survenant dans la structure sous-jacente du document se reflètent dans tous les objets NodeList et NamedNodeMap concernés. Par exemple, si un utilisateur du DOM prend un objet NodeList, contenant les enfants d'un objet Element, ajoute ensuite d'autres enfants à cet élément (ou en retire, ou en modifie), alors ces changements se répercutent automatiquement sur l'objet NodeList, sans autre action de la part de l'utilisateur. De la même manière, les changements sur un objet Node dans l'arbre se répercutent dans toutes les références à cet objet Node dans les objets NodeList et NamedNodeMap.

Finalement, les interfaces Text, Comment et CDATASection héritent toutes de l'interface CharacterData.

1.1.2. La gestion de la mémoire

La plupart des interfaces de programmation d'application définies par cette spécification se compose d'interfaces plutôt que de classes. Ce qui veut dire qu'une mise en œuvre doit seulement exposer les méthodes avec les noms et les opérations indiqués, et non pas appliquer les classes qui correspondent directement aux interfaces. Ceci permet une mise en œuvre des interfaces (API) du DOM comme une couche mince sur les applications existantes ayant leurs propres structures de données ou sur les applications plus récentes ayant différentes hiérarchies de classes. Ceci signifie également que les constructeurs ordinaires (au sens de Java ou C++) ne peuvent pas être utilisés pour créer des objets DOM, puisque les objets sous-jacents à construire ont peut-être peu de relations avec les interfaces DOM. Pour cela, la solution conventionnelle en conception orientée objet consiste à définir des méthodes de construction qui créent des instances d'objets mettant en œuvre les diverses interfaces. Les objets qui mettent en œuvre une interface X donnée sont créés par une méthode createX() de l'interface Document, car tous les objets DOM vivent dans le contexte d'un objet Document spécifique.

L'interface de programmation d'application (API) du DOM niveau 2 ne définit pas de moyen standard pour créer des objets DOMImplementation ; les mises en œuvre DOM doivent fournir une méthode spécialisée pour charger ces interfaces DOM qui permettent, dès lors, de construire tous les autres objets.

Les interfaces de programmation du DOM Core sont conçues pour être compatibles avec une grande variété de langages, des langages de script courants jusqu'aux langages plus performants utilisés principalement en programmation professionnelle. Ainsi, les interfaces de programmation du DOM doivent opérer selon diverses philosophies de gestion de la mémoire, allant des liaisons de langage qui n'exposent pas du tout la gestion de la mémoire à l'utilisateur, en passant par les langages (notamment Java) qui offrent des constructeurs explicites mais fournissent un mécanisme ramasse-miettes récupérant automatiquement la mémoire qui n'est plus utilisée, jusqu'à ceux (en particulier C/C++) qui imposent au programmeur une allocation explicite de la mémoire objet, une conservation de l'emplacement où elle est utilisée et une libération explicite pour sa réutilisation. Pour garantir un interface de programmation d'application (API) cohérentr entre ces plateformes, le DOM ne se préoccupe pas du tout de l'aspect gestion de la mémoire et laisse plutôt ce soin à la mise en œuvre. Aucune des liaisons de langage définies par l'interface de programmation d'application (API) du DOM (pour ECMAScript et Java) n'impose de méthodes de gestion de la mémoire, mais les liaisons du DOM avec d'autres langages (spécialement C ou C++) peuvent l'imposer. Les développeurs ont la responsabilité d'adapter l'interface de programmation d'application (API) du DOM à un langage particulier, ce n'est pas l'affaire du groupe de travail DOM.

1.1.3. Les conventions de nommage

Alors qu'il serait agréable d'avoir des noms d'attribut et de méthode qui soient courts, informatifs, cohérents en interne et familiers aux utilisateurs d'interface de programmation d'application (API) similaires, les noms ne devraient pas entrer en conflit avec ceux des interfaces de programmation légitimes gérées par les mises en œuvre DOM. En plus, les langages OMG IDL comme ECMAScript sont très limités pour lever l'ambiguïté qui peut résulter de noms issus d'espaces de nommage différents, ce qui fait qu'il est difficile d'éviter les conflits de nommage avec des noms courts et familiers. C'est pourquoi, les noms DOM tendent à être longs et descriptifs pour rester uniques dans tous les environnements.

Le groupe de travail a également essayé de rester cohérent en interne dans l'usage des divers termes, quoique ces choix puissent ne pas concorder avec ceux d'autres interfaces de programmation d'application (API). Par exemple, l'interface de programmation d'application (API) du DOM emploie le nom de méthode remove pour une modification du modèle de structure et le nom de méthode delete pour l'élimination de quelque chose à l'intérieur de ce modèle. La chose qui est supprimée [N.d.T. deleted] n'est pas retournée tandis que la chose retirée [N.d.T. removed] peut l'être au besoin.

1.1.4. L'héritage comparé aux vues à plat de l'interface de programmation d'application (API)

Les interfaces de programmation API du DOM Core présentent d'une certaine manière deux jeux d'interfaces différents vers un document XML/HTML : l'un offrant une approche orientée objet avec une hiérarchie d'héritage et l'autre offrant une vue simplifiée qui permet d'effectuer toute manipulation, via l'interface Node, sans nécessiter un forçage des valeurs (en Java et autres langages comme C) ou d'appels à une interface de requête en environnements COM. Ces opérations ayant un coût de traitemement assez important en Java et COM, on peut utiliser le DOM dans des environnements pour lesquels la performance est critique, et on autorise donc des fonctionnalités significatives en utilisant simplement l'interface Node. Comme de nombreux autres utilisateurs trouveront la hiérarchie d'héritage plus facile à appréhender que l'approche tout est nœud du DOM, on gère également des interfaces de haut niveau complètes pour ceux qui préfèrent une interface de programmation d'application (API) plus orienté objet.

En pratique, cela signifie qu'il y a une certaine redondance dans l'interface de programmation d'application (API). Le groupe de travail considère que l'approche héritage est la première vue de l'interface de programmation d'application (API) et le jeu complet de fonctionnalités bâti sur l'interface Node comme apportant des fonctionnalités supplémentaires que les utilisateurs peuvent employer, mais sans éliminer le besoin, qui serait dicté par une analyse orienté objet, de méthodes pour les autres interfaces. (Bien sûr, si l'analyse orienté objet produit un attribut (ou une méthode) identique à l'un des attributs (ou l'une des méthodes) de l'interface Node, on n'en définit alors pas d'entièrement redondant(e)). Ainsi, même s'il existe un attribut générique nodeName sur l'interface Node, il y a un attribut tagName sur l'interface Element ; ces deux attributs doivent contenir la même valeur, toutefois la question demeurant de savoir si cela vaut la peine de gérer les deux, au vu des différentes compositions que doit satisfaire l'interface de programmation d'application (API) du DOM.

1.1.5. Le type DOMString

Pour garantir une certaine interopérabilité, le DOM définit ce qui suit :

  • Définition du type DOMString

    Un type DOMString représente une séquence d'unités de 16 bits.


    Définition IDL
    valuetype DOMString sequence<unsigned short>;
    

  • Les applications doivent coder un type DOMString en se servant du codage UTF-16 (défini dans [Unicode] et dans le premier amendement de [ISO/IEC 10646]).
    Le codage UTF-16 a été choisi en raison de sa large diffusion dans l'industrie. Pour HTML et XML, remarquer que le jeu de caractères du document (et par là-même la notation des appels numériques de caractères) se fonde sur le Jeu universel de caractères (JUC) (N.D.T. UCS) [ISO-10646]. Un seul appel numérique de caractère peut donc, dans certains cas, correspondre à deux unités de 16 bits dans un type DOMString (une partie forte et une partie faible).

    Remarque : Bien que le DOM définisse le nom du type chaîne comme étant DOMString, des liaisons peuvent utiliser des noms différents. Par exemple pour Java, un type DOMString est lié au type String parce que ce type utilise aussi un codage UTF-16.

Remarque : En août 2000, la spécification OMG IDL ([OMGIDL]) comprenait un type wstring. Cependant, cette définition ne satisfaisait pas aux critères d'interopérabilité de l'interface de programmation d'application (API) du DOM, puisqu'elle s'appuyait sur une négociation pour décider de la taille et du codage d'un caractère.

1.1.6. Le type DOMTimeStamp

Pour garantir une certaine interopérabilité, le DOM définit ce qui suit :

  • Définition du type DOMTimeStamp

    Un type DOMTimeStamp représente un nombre de millisecondes.


    Définition IDL
    typedef unsigned long long DOMTimeStamp;
    

  • Remarque : bien que le DOM utilise le type DOMTimeStamp, les liaisons peuvent utiliser des types différents. Par exemple pour Java, le type DOMTimeStamp est lié au type long. En ECMAScript, le type DOMTimeStamp est lié au type Date parce que la capacité du type integer est trop petite.

1.1.7. Les comparaison de chaînes dans le DOM

Le DOM comprend beaucoup d'interfaces qui impliquent une correspondance de chaînes. Les processeurs HTML supposent généralement une normalisation des noms en majuscules (moins souvent, en minuscules), par exemple, pour les éléments, alors que les noms XML sont explicitement sensibles à la casse. Pour les besoins du DOM, la correspondance de chaînes s'effectue purement par comparaison binaire des unités de 16 bits du DOMString. En outre, le DOM suppose que toute normalisation de casse a lieu dans le processeur, avant que les structures du DOM ne soient construites.

Remarque : En marge de la casse, le texte peut recevoir des normalisations supplémentaires. Le groupe de travail I18N du W3C est en passe de définir exactement quelles sont les normalisations nécessaires et où celles-ci devraient s'appliquer. Le groupe de travail I18N prévoit d'imposer une normalisation précoce, c'est-à-dire que les données lues dans le DOM seront censées être déjà normalisées. Le DOM et les applications bâties sur celui-ci doivent seulement s'assurer, dans ce cas, que le texte reste normalisé au cours de ses modifications. Pour plus de détails, voir [Charmod].

1.1.8. Les espaces de nommage XML

Le DOM niveau 2 gère les espaces de nommage XML [Les espaces de nommage] en augmentant plusieurs interfaces du DOM niveau 1 Core pour la création et la manipulation des éléments et des attributs associés à un espace de nommage.

Pour ce qui est du DOM, les attributs spéciaux utilisés pour la déclaration des espaces de nommage XML sont toujours exposés et peuvent être manipulés comme n'importe quel autre attribut. Cependant, les nœuds restent liés en permanence aux adresses URI des espaces de nommage lors de leur création. En conséquence, le déplacement d'un nœud dans un document, en utilisant le DOM, ne produit en aucun cas un changement de son préfixe d'espace de nommage ou de son adresse URI d'espace de nommage. De la même façon, la création d'un nœud, avec un préfixe d'espace de nommage et une adresse URI d'espace de nommage, ou la modification du préfixe d'espace de nommage d'un nœud, ne se traduit pas dans un quelconque ajout, retrait ou changement des attributs spéciaux de déclaration d'espace de nommage XML concernés. La validation de l'espace de nommage n'est pas respectée ; c'est l'application DOM qui en est responsable. En particulier, puisque la correspondance entre les préfixes et les adresses URI des espaces de nommage n'est pas respectée, on ne peut pas en général sérialiser naïvement le document résultant. Par exemple, les applications devront peut-être déclarer chaque espace de nommage utilisé lors de la sérialisation d'un document.

Le DOM niveau 2 n'effectue aucune normalisation d'adresse URI ou canonisation. Les adresses URI transmises au DOM sont censées être valides (par exemple, les caractères comme les caractères blancs sont correctement masqués), aucune vérification lexicale n'a lieu. Les appels d'adresse URI sont traités comme des chaînes et comparés littéralement. Le traitement de l'appel d'adresse URI relatif d'un espace de nommage n'est pas défini. Pour assurer une interopérabilité minimale, on devrait seulement employer des appels d'adresse URI absolus d'espaces de nommage (c.à.d., les appels d'adresse URI commençant par un nom de système avec un caractère deux-points). Puisque le DOM n'effectue aucune vérification lexicale, remarquer que la chaîne vide sera traitée comme une adresse URI d'espace de nommage réel dans les méthodes DOM niveau 2. Les applications doivent utiliser la valeur null comme paramètre namespaceURI pour ces méthodes, si aucun espace de nommage n'est voulu. Les applications devraient utiliser la valeur null comme paramètre namespaceURI pour ces méthodes si aucun espace de nommage n'est voulu. Dans les langages de programmation où on peut différencier les chaînes vides de la valeur null, la façon dont ces chaînes vides sont traitées, quand elles sont passées comme adresse URI d'espace de nommage à une méthode DOM niveau 2, dépendra de la mise en œuvre. Cela reste vrai même si le DOM ne fait aucune vérification lexicale sur les adresses URI.

Remarque : Une déclaration setAttributeNS(null, ...) place l'attribut dans les partitions par type d'élément.

Remarque : Dans le DOM, tous les attributs de déclaration d'espace de nommage sont, par définition, liés à l'adresse URI de l'espace de nommage "http://www.w3.org/2000/xmlns/" →vf. Il s'agit des attributs dont le préfixe d'espace de nommage ou le nom qualifié sont "xmlns". Bien que (au moment de la publication) ce point ne fasse pas partie de la spécification des espaces de nommage XML [Les espaces de nommage], son incorporation est prévue dans une révision ultérieure.

Dans un document sans espace de nommage, la liste enfant d'un nœud EntityReference est toujours la même que celle du nœud Entity correspondant. Ceci n'est pas vrai pour un document dans lequel une entité contient des préfixes d'espaces de nommage non liés. Auquel cas, les descendants des nœuds EntityReference correspondants peuvent être liés à des adresses URI d'espaces de nommage différentes, en fonction de l'emplacement des références d'entité. Également, puisque dans le DOM les nœuds restent toujours liés à la même adresse URI d'espace de nommage, le déplacement de ces nœuds EntityReference peut donner des documents qui ne peuvent pas être sérialisés. Cela se vérifie aussi quand on se sert de la méthode createEntityReference de l'interface Document DOM niveau 1 pour créer des appels d'entité qui correspondent à ces entités, puisque les descendants de l'objet EntityReference retourné ne sont pas liés. Le DOM niveau 2 n'offre aucun mécanisme pour la résolution des préfixes d'espaces de nommage. Pour toutes ces raisons, on devrait éviter d'utiliser ces entités et appels d'entité ou tout au moins y faire très attention. Un niveau ultérieur du DOM pourrait inclure d'autres moyens pour les gérer.

Les nouvelles méthodes, comme createElementNS et createAttributeNS de l'interface Document, sont prévues pour une utilisation par des applications reconnaissant les espaces de nommage. Les applications simples, qui n'utilisent pas les espaces de nommage, peuvent employer les méthodes DOM niveau 1, comme createElement et createAttribute. Les éléments et les attributs créés de cette façon n'ont pas de préfixe d'espace de nommage, d'adresse URI d'espace de nommage ou de nom local.

Remarque : Les méthodes DOM niveau 1 ignorent les espaces de nommage. Quoique leur utilisation soit sûre quand les espaces de nommage n'interviennent pas, on devrait éviter de les employer simultanément avec les nouvelles méthodes. Les méthodes DOM niveau 1 identifient les nœuds d'attribut uniquement par leur attribut nodeName. Au contraire, les méthodes DOM niveau 2 liées à des espaces de nommage, identifient les nœuds d'attribut par leurs attributs namespaceURI et localName. Du fait de cette distinction fondamentale, le mélange des deux jeux de méthodes peut conduire à un résultat imprévisible. Notamment, en utilisant la méthode setAttributeNS, un élément peut avoir deux attributs (ou plus) avec le même attribut nodeName, mais des attributs namespaceURI différents. Un appel de la méthode getAttribute avec cette valeur nodeName pourra alors retourner l'un d'eux. Le résultat dépend de la mise en œuvre. De la même manière, en utilisant la méthode setAttributeNode, on peut fixer deux attributs (ou plus) avec des valeurs nodeName différentes mais les mêmes préfixe et valeur namespaceURI. Auquel cas, la méthode getAttributeNodeNS retournera l'un ou l'autre attribut, selon la mise en œuvre. La seule certitude, dans ces cas, c'est que toutes les méthodes qui désignent un article nommé par son attribut nodeName s'adresseront au même article et que toutes les méthodes qui désignent un nœud par son adresse URI ou son nom local s'adresseront au même nœud. Par exemple, les méthodes setAttribute et setAttributeNS affectent les nœuds respectifs retournés par les méthodes getAttribute et getAttributeNS.

1.2. Les interfaces fondamentales

On considère que les interfaces de cette section sont fondamentales et, sauf indication contraire, elles doivent être mises en œuvre en totalité par toutes les applications conformes au DOM, y compris toutes les mises en œuvre HTML DOM [DOM niveau 2 HTML].

Une application DOM peut utiliser la méthode hasFeature(feature, version) de l'interface DOMImplementation, avec les paramètres "Core" et "2.0" respectivement, pour déterminer si ce module est géré ou non par la mise en œuvre. Toute mise en œuvre conforme au DOM niveau 2 ou à un de ses modules, doit se conformer au module Core. Pour plus d'informations, se reporter à la section sur la conformité dans cette spécification.

Exception DOMException

Les opérations DOM ne soulèvent des exceptions que dans des circonstances exceptionnelles, c.à.d., quand une opération est impossible à réaliser (soit pour des raisons logiques, car des données sont manquantes, soit parce que la mise en œuvre est devenue instable). En général, les méthodes DOM retournent des valeurs d'erreur spécifiques au cours de situations de traitement ordinaires, telle qu'une erreur de dépassement dans l'utilisation d'un nœud NodeList.

Les mises en œuvre devraient soulever d'autres exceptions en d'autres circonstances. Par exemple, la mise en œuvre devrait soulever une exception spécifique au passage d'un argument de valeur null si cette valeur est inattendue.

Certains systèmes de langage et d'objet ne gèrent pas le concept d'exception. Pour ces systèmes, les conditions d'erreur peuvent être signalées à l'aide de mécanismes de relevé d'erreurs natifs. Pour certaines liaisons, par exemple, les méthodes peuvent retourner des codes d'erreur similaires à ceux listés dans les descriptions de méthode correspondantes.


Définition IDL
exception DOMException {
unsigned short   code;
};
// ExceptionCode
const unsigned short      INDEX_SIZE_ERR                 = 1;
const unsigned short      DOMSTRING_SIZE_ERR             = 2;
const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
const unsigned short      WRONG_DOCUMENT_ERR             = 4;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
const unsigned short      NOT_FOUND_ERR                  = 8;
const unsigned short      NOT_SUPPORTED_ERR              = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
// Introduite dans DOM niveau 2 :
const unsigned short      INVALID_STATE_ERR              = 11;
// Introduite dans DOM niveau 2 :
const unsigned short      SYNTAX_ERR                     = 12;
// Introduite dans DOM niveau 2 :
const unsigned short      INVALID_MODIFICATION_ERR       = 13;
// Introduite dans DOM niveau 2 :
const unsigned short      NAMESPACE_ERR                  = 14;
// Introduite dans DOM niveau 2 :
const unsigned short      INVALID_ACCESS_ERR             = 15;

Groupe de définition ExceptionCode

Un entier indiquant le type de l'erreur générée.

Remarque : D'autres codes numériques sont réservés par le W3C pour un éventuel usage ultérieur.

Constantes définies
DOMSTRING_SIZE_ERR
Si l'étendue spécifiée pour le texte ne tient pas dans un type DOMString.
HIERARCHY_REQUEST_ERR
Si un nœud est inséré à une position qui ne convient pas.
INDEX_SIZE_ERR
Si l'index ou la taille sont négatifs ou supérieurs à la valeur admise.
INUSE_ATTRIBUTE_ERR
Si on essaye d'ajouter un attribut déjà en cours d'utilisation ailleurs.
INVALID_ACCESS_ERR, introduit dans DOM niveau 2.
Si un paramètre ou une opération ne sont pas gérés par l'objet sous-jacent.
INVALID_CHARACTER_ERR
Si un caractère invalide ou illégal est spécifié, comme dans un nom. Voir, dans la spécification XML, la production 2→vf pour la définition d'un caractère légal et la production 5→vf pour celle d'un caractère légal pour un nom.
INVALID_MODIFICATION_ERR, introduit dans DOM niveau 2.
Si on essaye de modifier le type de l'objet sous-jacent.
INVALID_STATE_ERR, introduit dans DOM niveau 2.
Si on essaye d'utiliser un objet qui n'est pas, ou n'est plus, utilisable.
NAMESPACE_ERR, introduit dans DOM niveau 2.
Si on essaye de créer ou de changer un objet de manière incorrecte pour ce qui est de l'espace de nommage.
NOT_FOUND_ERR
Si on essaye d'appeler un œud dans un contexte où celui-ci est inexistant.
NOT_SUPPORTED_ERR
Si la mise en œuvre ne gère pas le type d'objet ou l'opération demandés.
NO_DATA_ALLOWED_ERR
Si on spécifie des données pour un nœud qui ne les gère pas.
NO_MODIFICATION_ALLOWED_ERR
Si on essaye de modifier un objet alors que les modifications ne sont pas admises.
SYNTAX_ERR, introduit dans DOM niveau 2.
Si on spécifie une chaîne invalide ou illégale.
WRONG_DOCUMENT_ERR
Si on utilise un nœud dans un document différent de celui qui l'a créé (et qu'il ne le gère pas).
L'interface DOMImplementation

L'interface DOMImplementation fournit un certain nombre de méthodes pour effectuer des opérations qui sont indépendantes de toute instance particulière du modèle objet du document.


Définition IDL
interface DOMImplementation {
  boolean            hasFeature(in DOMString feature, 
                                in DOMString version);
  // Introduite dans DOM niveau 2 :
  DocumentType       createDocumentType(in DOMString qualifiedName, 
                                        in DOMString publicId, 
                                        in DOMString systemId)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  Document           createDocument(in DOMString namespaceURI, 
                                    in DOMString qualifiedName, 
                                    in DocumentType doctype)
                                        raises(DOMException);
};

Méthodes
createDocument introduit dans DOM niveau 2
Crée un objet XML Document du type indiqué avec son élément document. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode. Crée un objet DOM Document du type indiqué avec son élément document.
Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'élément document à créer.
qualifiedName de type DOMString
Le nom qualifié de l'élément document à créer.
doctype de type DocumentType
Le type du document à créer ou la valeur null.
Quand la valeur de doctype n'est pas null, la valeur de son attribut Node.ownerDocument correspond au document à créer.
Valeur retournée

Document

Un nouvel objet Document.

Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal.

NAMESPACE_ERR : Soulevée si qualifiedName est malformé, si qualifiedName a un préfixe et namespaceURI a une valeur de null, ou si qualifiedName a un préfixe qui est "xml" et namespaceURI est différent de "http://www.w3.org/XML/1998/namespace" [Les espaces de nommage].

WRONG_DOCUMENT_ERR : Soulevée si doctype est déjà utilisé dans un document différent ou a été créé par une mise en œuvre différente.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

createDocumentType introduit dans DOM niveau 2
Crée un nœud DocumentType vide. Les déclarations d'entité et leurs notations ne sont pas disponibles. La résolution des appels d'entité et l'ajout des attributs implicites n'ont pas lieu. Il est prévu qu'une version ultérieure du DOM fournisse un moyen de peupler un DocumentType.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.
Paramètres
qualifiedName de type DOMString
Le nom qualifié du type de document à créer.
publicId de type DOMString
Le sous-ensemble d'identifiant public externe.
systemId de type DOMString
Le sous-ensemble d'identifiant système externe.
Valeur retournée

DocumentType

Un nouveau nœud DocumentType avec son attribut Node.ownerDocument mis à null.

Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal.

NAMESPACE_ERR : Soulevée si qualifiedName est malformé.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

hasFeature
Teste de la mise en œuvre DOM si celle-ci gère une fonctionnalité spécifique.
Paramètres
feature de type DOMString
Le nom de la fonctionnalité à tester (insensible à la casse). Les valeurs utilisées par les fonctionnalités DOM sont définies dans les modules de la spécification DOM niveau 2 et sont listés dans la section traitant de la conformité. Ce nom doit être un nom XML. Par convention, et pour éviter les conflits éventuels, les noms qui se rapportent à des fonctionnalités définies en-dehors de la spécification DOM devraient être rendus uniques en inversant le nom du domaine Internet de la personne (ou de l'organisation dont celle-ci fait partie) qui définit la fonctionnalité, composant par composant, et en utilisant le résultat obtenu comme préfixe. Par exemple, le groupe de travail SVG du W3C définit la fonctionnalité "org.w3c.dom.svg".
version de type DOMString
C'est le numéro de version de la fonctionnalité à tester. Pour le niveau 2, la chaîne peut être "2.0" ou bien "1.0". Si la version n'est pas indiquée a la valeur null ou la chaîne vide, la méthode renverra la valeur true indiquant une gestion de toute version de la fonctionnalité.
Valeur retournée

boolean

true si la fonctionnalité est mise en œuvre dans la version indiquée, sinon false.

Aucune exception
L'interface DocumentFragment

DocumentFragment est un objet Document allégé ou minimal. On souhaite très souvent pouvoir extraire une portion de l'arbre du document ou créer un nouveau fragment de document. Imaginez de mettre en œuvre une commande d'utilisateur comme couper ou de réarranger un document en déplaçant des fragments. Un objet qui puisse contenir de tels fragments est souhaitable et il semble assez naturel d'utiliser un nœud pour le faire. Quoiqu'un objet Document puisse tenir ce rôle, ce Document est potentiellement un objet poids lourd, en fonction de la mise en œuvre sous-jacente. Ce qui fait vraiment l'affaire, c'est un objet de très faible poids. Et DocumentFragment est justement cet objet.

En outre, des opérations diverses, tel qu'insérer des nœuds comme enfants d'un autre objet Node, peuvent admettre des objets DocumentFragment comme arguments. Le résultat est le suivant : tous les nœuds enfants de l'objet DocumentFragment sont transférés dans la liste des enfants de ce nœud.

Les enfants d'un nœud DocumentFragment, au nombre de zéro ou plus nœuds, représentent les têtes des sous-arbres définissant la structure du document. Les nœuds DocumentFragment ne sont pas obligatoirement des documents XML bien formés (quoiqu'ils doivent nécessairement suivre les règles imposées aux entités analysables XML bien formées, qui peuvent avoir plusieurs nœuds de tête). Par exemple, un DocumentFragment peut n'avoir qu'un seul enfant, peut-être un nœud Text. Un tel modèle de structure ne constitue pas un document HTML ni un document XML bien formé.

Quand un nœud DocumentFragment est inséré dans un Document (ou, en fait, dans tout autre Node qui accepte des enfants), les enfants de l'objet DocumentFragment, et non l'objet DocumentFragment en question, sont insérés dans le Node. Par conséquent, l'objet DocumentFragment est très utile lorsque l'utilisateur souhaite créer des nœuds frères ; l'objet DocumentFragment fait alors office de parent pour ces nœuds et l'utilisateur peut donc employer les méthodes standards de l'interface Node, telles que insertBefore et appendChild.


Définition IDL
interface DocumentFragment : Node {
};

L'interface Document

L'interface Document représente le document HTML, ou XML, entier. Conceptuellement, c'est la racine de l'arbre du document, qui offre l'accès primaire aux données du document.

Puisque les éléments, les nœuds de texte, les commentaires, les instructions de traitement, etc., ne peuvent pas exister en-dehors du contexte d'un Document, l'interface Document contient aussi les méthodes nécessaires pour créer ces objets. Les objets Node créés possèdent un attribut ownerDocument qui les associent au Document dans le contexte duquel ils ont été créés.


Définition IDL
interface Document : Node {
  readonly attribute DocumentType     doctype;
  readonly attribute DOMImplementation  implementation;
  readonly attribute Element          documentElement;
  Element            createElement(in DOMString tagName)
                                        raises(DOMException);
  DocumentFragment   createDocumentFragment();
  Text               createTextNode(in DOMString data);
  Comment            createComment(in DOMString data);
  CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
  ProcessingInstruction createProcessingInstruction(in DOMString target, 
                                                    in DOMString data)
                                        raises(DOMException);
  Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
  EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString tagname);
  // Introduite dans DOM niveau 2 :
  Node               importNode(in Node importedNode, 
                                in boolean deep)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  Element            createElementNS(in DOMString namespaceURI, 
                                     in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  Attr               createAttributeNS(in DOMString namespaceURI, 
                                       in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI, 
                                            in DOMString localName);
  // Introduite dans DOM niveau 2 :
  Element            getElementById(in DOMString elementId);
};

Attributs
doctype de type DocumentType, en lecture seule
La déclaration de type de document (voir DocumentType) associée à ce document. Pour les documents HTML comme XML sans déclaration de type de document, c'est la valeur null qui est retournée. Le DOM niveau 2 ne gère pas l'édition de la déclaration de type de document. On ne peut altérer docType d'aucune façon, même en utilisant les méthodes héritées de l'interface Node, telles que insertNode ou removeNode.
documentElement de type Element, en lecture seule
C'est un attribut de commodité qui permet un accès direct au nœud enfant qui est l'élément racine du document. Pour les documents HTML, c'est l'élément dont la valeur de l'attribut tagName est "HTML".
implementation de type DOMImplementation, en lecture seule
L'objet DOMImplementation qui contient ce document. Une application DOM peut utiliser des objets issus de plusieurs mises en œuvre.
Méthodes
createAttribute
Crée un objet Attr avec le nom fourni. Remarquer que l'instance Attr peut alors être placée sur un objet Element en utilisant la méthode setAttributeNode.
Pour créer un attribut avec un nom qualifié et une adresse URI d'espace de nommage, utiliser la méthode createAttributeNS.
Paramètres
name de type DOMString
Le nom de l'attribut.
Valeur retournée

Attr

Un nouvel objet Attr avec l'attribut nodeName qui prend la valeur du paramètre name, les paramètres localName, prefix et namespaceURI ayant la valeur null. La valeur de cet attribut est la chaîne vide.

Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal.

createAttributeNS introduit dans DOM niveau 2
Crée un attribut du nom qualifié et de l'adresse URI d'espace de nommage fournis. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à créer.
qualifiedName de type DOMString
Le nom qualifié de l'attribut à instancier.
Valeur retournée

Attr

Un nouvel objet Attr avec les attributs suivants :

Attribut Valeur
Node.nodeName qualifiedName
Node.namespaceURI namespaceURI
Node.prefix préfixe, extrait de qualifiedName, ou null s'il n'y a aucun préfixe
Node.localName nom local, extrait de qualifiedName
Attr.name qualifiedName
Node.nodeValue la chaîne vide
Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML].

NAMESPACE_ERR : Soulevée si qualifiedName est malformé selon la spécification des espaces de nommage dans XML, ou si qualifiedName a un préfixe et namespaceURI est null, ou si qualifiedName a un préfixe qui est "xml" et namespaceURI est différent de "http://www.w3.org/XML/1998/namespace", ou si qualifiedName (ou son préfixe) est "xmlns" et namespaceURI est différent de "http://www.w3.org/2000/xmlns/".

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

createCDATASection
Crée un nœud CDATASection dont la valeur est la chaîne indiquée.
Paramètres
data de type DOMString
Les données pour le contenu de CDATASection.
Valeur retournée

CDATASection

Le nouvel objet CDATASection.

Exceptions

DOMException

NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML.

createComment
Crée un nœud Comment qui reçoit la chaîne indiquée.
Paramètres
data de type DOMString
Les données pour le nœud.
Valeur retournée

Comment

Le nouvel objet Comment.

Aucune exception
createDocumentFragment
Crée un objet DocumentFragment vide.
Valeur retournée
Aucun paramètre
Aucune exception
createElement
Crée un élément du type indiqué. Remarquer que l'instance retournée met en œuvre l'interface Element, et les attributs peuvent donc être définis directement sur l'objet retourné.
En outre, s'il y a des attributs dont on sait qu'ils ont une valeur par défaut, des nœuds Attr les représentant sont automatiquement créés et liés à l'élément.
Pour créer un élément avec un nom qualifié et une adresse URI d'espace de nommage, utiliser la méthode createElementNS.
Paramètres
tagName de type DOMString
Le nom du type d'élément à instancier. Insensible à la casse pour XML. Pour HTML, on peut fournir dans tous les cas un paramètre tagName, mais la mise en œuvre doit le faire correspondre avec la forme canonique.
Valeur retournée

Element

Un nouvel objet Element avec l'attribut nodeName qui prend la valeur du paramètre tagName, les paramètres localName, prefix et namespaceURI ayant la valeur null.

Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal.

createElementNS introduit dans DOM niveau 2
Crée un élément de nom qualifié et d'adresse URI d'espace de nommage donnés. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.
Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'élément à créer.
qualifiedName de type DOMString
Le nom qualifié de l'élément à instancier.
Valeur retournée

Element

Un nouvel objet Element avec les attributs suivants :

Attribut Valeur
Node.nodeName qualifiedName
Node.namespaceURI namespaceURI
Node.prefix préfixe, extrait de qualifiedName, ou null s'il n'y a aucun préfixe
Node.localName nom local, extrait de qualifiedName
Element.tagName qualifiedName
Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML].

NAMESPACE_ERR : Soulevée si qualifiedName est malformé selon la spécification des espaces de nommage dans XML, ou si qualifiedName a un préfixe et namespaceURI est null, ou si qualifiedName a un préfixe qui est "xml" et namespaceURI est différent de "http://www.w3.org/XML/1998/namespace" [Les espaces de nommage].

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

createEntityReference
Crée un objet EntityReference. En outre, si l'entité appelée est connue, la liste des enfants du nœud EntityReference devient la même que celle du nœud Entity correspondant.

Remarque : Si un descendant du nœud Entity a un préfixe d'espace de nommage non lié, le nœud EntityReference correspondant est également non lié (son paramètre namespaceURI est null). Le DOM niveau 2 ne gère aucun mécanisme de résolution des préfixes d'espaces de nommage.

Paramètres
name de type DOMString
Le nom de l'entité à appeler.
Valeur retournée

EntityReference

Le nouvel objet EntityReference.

Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal.

NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML.

createProcessingInstruction
Crée un nœud ProcessingInstruction qui reçoit le nom indiqué et des chaînes de données.
Paramètres
target de type DOMString
La partie cible de l'instruction de traitement.
data de type DOMString
Les données pour le nœud.
Valeur retournée
Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevé si la cible indiquée contient un caractère illégal.

NOT_SUPPORTED_ERR : Soulevée s'il s'agit d'un document HTML.

createTextNode
Crée un nœud Text qui reçoit la chaîne indiquée.
Paramètres
data de type DOMString
Les données pour le nœud.
Valeur retournée

Text

Le nouvel objet Text.

Aucune exception
getElementById introduit dans DOM niveau 2
Retourne l'Element dont l'ID est donné par l'attribut elementId. S'il n'existe pas un tel élément, retourne null. Le comportement n'est pas défini si plusieurs éléments ont cet ID.

Remarque : La mise en œuvre DOM doit conserver l'information qui précise quels attributs sont du type ID. Les attributs avec le nom "ID" ne sont pas du type ID, à moins d'être définis comme tel. Les mises en œuvre, ne sachant pas si des attributs sont ou non du type ID, sont censées retourner null.

Paramètres
elementId de type DOMString
La valeur id unique d'un élément.
Valeur retournée

Element

L'élément correspondant.

Aucune exception
getElementsByTagName
Retourne un objet NodeList de tous les Element avec un nom de balise donné, dans l'ordre de leur rencontre au cours de la traversée préordonnée de l'arbre de Document.
Paramètres
tagname de type DOMString
Le nom de la balise à rechercher. La valeur spéciale "*" correspond à toutes les balises.
Valeur retournée

NodeList

Un nouvel objet NodeList qui contient tous les Element relevés.

Aucune exception
getElementsByTagNameNS introduit dans DOM niveau 2
Retourne un objet NodeList de tous les Element avec un nom local et une adresse URI d'espace de nommage donnés dans l'ordre de leur rencontre au cours de la traversée préordonnée de l'arbre de Document. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.
Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage des éléments à rechercher. La valeur spéciale "*" correspond à tous les espaces de nommage.
localName de type DOMString
Le nom local des éléments à rechercher. La valeur spéciale "*" correspond à tous les noms locaux.
Valeur retournée

NodeList

Un nouvel objet NodeList qui contient tous les Element relevés.

Aucune exception
Exception

DOMException

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

importNode introduit dans DOM niveau 2
Importe un nœud d'un autre document que le document présent. Le nœud retourné n'a aucun parent (l'attribut parentNode est null). Le nœud source n'est ni altéré ni retiré du document original ; cette méthode crée une nouvelle copie du nœud source.
Pour tous les nœuds, l'import d'un nœud crée un objet Node appartenant au document qui l'importe, avec des valeurs d'attribut identiques à celles des attributs nodeName et nodeType du nœud source, plus les attributs relatifs aux espaces de nommage (prefix, localName et namespaceURI). Comme pour l'opération cloneNode sur un Node, le nœud source n'est pas altéré.
D'autres informations sont recopiées en fonction de la valeur de nodeType, en essayant de reproduire le comportement attendu si un fragment de la source XML, ou HTML, était copié d'un document à l'autre, en reconnaissant que deux documents peuvent avoir des DTD différents dans le cas de XML. La liste suivante décrit les particularités de chaque type de nœud.
ATTRIBUTE_NODE
L'attribut ownerElement reçoit la valeur de null et le drapeau specified la valeur true sur l'objet Attr généré ; Les descendants du nœud source Attr sont importés récursivement et les nœuds résultants réassemblés pour former le sous-arbre correspondant.
Remarquer que le paramètre deep n'a aucun effet sur les nœuds Attr ; ceux-ci emportent toujours leurs enfants lors de leur import.
DOCUMENT_FRAGMENT_NODE
Si l'option deep reçoit la valeur true, les descendants de l'élément source sont importés récursivement et les nœuds résultants réassemblés pour former le sous-arbre correspondant. Sinon un objet DocumentFragment vide est simplement généré.
DOCUMENT_NODE
Les nœuds Document ne peuvent pas être importés.
DOCUMENT_TYPE_NODE
Les nœuds DocumentType ne peuvent pas être importés.
ELEMENT_NODE
Les nœuds de l'élément source avec des attributs spécifiés sont importés et les nœuds Attr générés sont liés à l'objet Element généré. Les attributs implicites ne sont pas recopiés, quoique si le document à importer définit des attributs implicites pour ce nom d'élément, ceux-ci sont assignés. Si le paramètre deep de la méthode importNode a la valeur true, les descendants de l'élément source sont importés récursivement et les nœuds résultants réassemblés pour former le sous-arbre correspondant.
ENTITY_NODE
Les nœuds Entity peuvent être importés mais, pour la version courante du DOM, l'objet DocumentType est en lecture seule. La possibilité de rajouter ces nœuds importés à un DocumentType est envisagé pour une version ultérieure du DOM.
Lors d'un import, les attributs publicId, systemId et notationName sont recopiés. Si un import avec deep vérifié est demandé, les descendants de l'objet Entity source sont importés et les nœuds résultants réassemblés pour former le sous-arbre correspondant.
ENTITY_REFERENCE_NODE
Seul l'objet EntityReference en question est recopié, même si un import avec deep vérifié est demandé, puisque la source et le document de destination peuvent avoir défini l'entité différemment. Si le document importé fournit une définition pour ce nom d'entité, sa valeur est assignée.
NOTATION_NODE
Les nœuds Notation peuvent être importés mais, dans la version courante du DOM, l'objet DocumentType est en lecture seule. La possibilité de rajouter ces nœuds importés à un DocumentType est envisagé pour une version ultérieure du DOM.
Lors d'un import, les attributs publicId et systemId sont recopiés.
Remarquer que le paramètre deep n'a aucun effet sur les nœuds Notation puisque ceux-ci n'ont jamais aucun enfant.
PROCESSING_INSTRUCTION_NODE
Le nœud importé recopie les valeurs de ses attributs target et data sur celles du nœud source.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
Ces trois types de nœud, qui héritent de CharacterData, recopient les valeurs de leurs attributs data et length sur celles du nœud source.
Paramètres
importedNode de type Node
Le nœud à importer.
deep de type boolean
Pour la valeur true, importe récursivement le sous-arbre à partir du nœud indiqué ; pour la valeur false, n'importe que le nœud en question, comme expliqué ci-dessus. Ceci n'a aucun effet sur les nœuds Attr, EntityReference et Notation.
Valeur retournée

Node

Le nœud importé qui apparatient à ce Document.

Exceptions

DOMException

NOT_SUPPORTED_ERR : Soulevée si le type du nœud n'est pas reconnu.

L'interface Node

L'interface Node est le type de données principal pour le modèle objet de document dans son ensemble. Elle représente un seul nœud dans l'arbre du document. Bien que tous les objets mettant en œuvre l'interface Node exposent des méthodes pour la gestion des enfants, certains ne peuvent pas avoir d'enfants. Par exemple, les nœuds Text ne peuvent pas avoir d'enfants, et ajouter un enfant à ces nœuds soulève alors une exception DOMException.

Les attributs nodeName, nodeValue et attributes composent un mécanisme permettant d'accéder aux informations d'un nœud sans devoir faire appel aux interfaces dérivées spécifiques. Au cas où il n'y aurait pas de correspondance évidente entre ces attributs et un type de nœud particulier (par exemple, nodeValue pour un objet Element ou attributes pour un objet Comment), la valeur null est retournée. Remarquer que les interfaces spécialisées peuvent offrir des mécanismes supplémentaires plus pratiques pour obtenir ou fixer les informations pertinentes.


Définition IDL
interface Node {

  // Type de nœud
  const unsigned short      ELEMENT_NODE                   = 1;
  const unsigned short      ATTRIBUTE_NODE                 = 2;
  const unsigned short      TEXT_NODE                      = 3;
  const unsigned short      CDATA_SECTION_NODE             = 4;
  const unsigned short      ENTITY_REFERENCE_NODE          = 5;
  const unsigned short      ENTITY_NODE                    = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
  const unsigned short      COMMENT_NODE                   = 8;
  const unsigned short      DOCUMENT_NODE                  = 9;
  const unsigned short      DOCUMENT_TYPE_NODE             = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
  const unsigned short      NOTATION_NODE                  = 12;

  readonly attribute DOMString        nodeName;
           attribute DOMString        nodeValue;
                            // soulève une exception DOMException à l'initialisation
                            // soulève une exception DOMException en retour

  readonly attribute unsigned short   nodeType;
  readonly attribute Node             parentNode;
  readonly attribute NodeList         childNodes;
  readonly attribute Node             firstChild;
  readonly attribute Node             lastChild;
  readonly attribute Node             previousSibling;
  readonly attribute Node             nextSibling;
  readonly attribute NamedNodeMap     attributes;
  // Modifié dans DOM niveau 2 :
  readonly attribute Document         ownerDocument;
  Node               insertBefore(in Node newChild, 
                                  in Node refChild)
                                        raises(DOMException);
  Node               replaceChild(in Node newChild, 
                                  in Node oldChild)
                                        raises(DOMException);
  Node               removeChild(in Node oldChild)
                                        raises(DOMException);
  Node               appendChild(in Node newChild)
                                        raises(DOMException);
  boolean            hasChildNodes();
  Node               cloneNode(in boolean deep);
  // Modifié dans DOM niveau 2 :
  void               normalize();
  // Introduite dans DOM niveau 2 :
  boolean            isSupported(in DOMString feature, 
                                 in DOMString version);
  // Introduite dans DOM niveau 2 :
  readonly attribute DOMString        namespaceURI;
  // Introduite dans DOM niveau 2 :
           attribute DOMString        prefix;
                                 // soulève une exception DOMException à l'initialisation

  // Introduite dans DOM niveau 2 :
  readonly attribute DOMString        localName;
  // Introduite dans DOM niveau 2 :
  boolean            hasAttributes();
};

Groupe de définition NodeType

Un entier indiquant le type du nœud en question.

Remarque : Les codes numériques jusqu'à 200 sont réservés par le W3C pour un possible usage ultérieur.

Constantes définies
ATTRIBUTE_NODE
Le nœud est un objet Attr.
CDATA_SECTION_NODE
Le nœud est un objet CDATASection.
COMMENT_NODE
Le nœud est un objet Comment.
DOCUMENT_FRAGMENT_NODE
Le nœud est un objet DocumentFragment.
DOCUMENT_NODE
Le nœud est un objet Document.
DOCUMENT_TYPE_NODE
Le nœud est un objet DocumentType.
ELEMENT_NODE
Le nœud est un objet Element.
ENTITY_NODE
Le nœud est un objet Entity.
ENTITY_REFERENCE_NODE
Le nœud est un objet EntityReference.
NOTATION_NODE
Le nœud est un objet Notation.
PROCESSING_INSTRUCTION_NODE
Le nœud est un objet ProcessingInstruction.
TEXT_NODE
Le nœud est un objet Text.

Les valeurs des attributs nodeName, nodeValue et attributes varient en fonction du type du nœud, comme suit :

Interface nodeName nodeValue attributes
Attr nom de l'attribut valeur de l'attribut null
CDATASection #cdata-section contenu de la section CDATA null
Comment #comment contenu du commentaire null
Document #document null null
DocumentFragment #document-fragment null null
DocumentType nom du type de document null null
Element nom de la balise null objet NamedNodeMap
Entity nom de l'entité null null
EntityReference nom de l'entité appelée null null
Notation nom de la notation null null
ProcessingInstruction valeur de target contenu entier en excluant target null
Text #text contenu du nœud de texte null
Attributs
attributes de type NamedNodeMap, en lecture seule
Un objet NamedNodeMap contenant les attributs de ce nœud (si c'est un objet Element), sinon la valeur null.
childNodes de type NodeList, en lecture seule
Un objet NodeList qui contient tous les enfants de ce nœud. S'il n'y a aucun enfant, c'est un objet NodeList ne contenant aucun nœud.
firstChild de type Node, en lecture seule
Le premier enfant de ce nœud. S'il n'y a pas un tel nœud, retourne la valeur null.
lastChild de type Node, en lecture seule
Le dernier enfant de ce nœud. S'il n'y pas un tel nœud, retourne la valeur null.
localName de type DOMString, en lecture seule, introduit dans DOM niveau 2
Retourne la partie locale du nom qualifié de ce nœud.
Pour les nœuds de tout autre type que ELEMENT_NODE ou ATTRIBUTE_NODE et pour les nœuds créés avec une méthode DOM niveau 1, telle que la méthode createElement de l'interface Document, c'est toujours la valeur null qui est retournée.
namespaceURI de type DOMString, en lecture seule, introduit dans DOM niveau 2
L'adresse URI d'espace de nommage de ce nœud, ou la valeur null si ce n'est pas indiqué.
Ce n'est pas la valeur calculée résultant d'une recherche d'espace de nommage basée sur l'examen des déclarations d'espaces de nommage en place. C'est simplement l'adresse URI d'espace de nommage fournie au moment de la création.
Pour les nœuds de tout autre type que ELEMENT_NODE ou ATTRIBUTE_NODE et pour les nœuds créés par une méthode DOM niveau 1, telle que la méthode createElement de l'interface Document, c'est toujours la valeur null qui est retournée.

Remarque : Selon la spécification des espaces de nommage en XML [Les espaces de nommage], un attribut n'hérite pas de l'espace de nommage de l'élément auquel il se rapporte. Si on ne donne pas explicitement d'espace de nommage, l'attribut n'en a simplement pas.

nextSibling de type Node, en lecture seule
Le nœud qui suit immédiatement ce nœud. S'il n'y a pas un tel nœud, c'est la valeur null qui est retournée.
nodeName de type DOMString, en lecture seule
Le nom de ce nœud, en fonction de son type ; voir la table ci-dessus.
nodeType de type unsigned short, en lecture seule
Un code représentant le type de l'objet sous-jacent, comme défini ci-dessus.
nodeValue de type DOMString
La valeur de ce nœud, en fonction de son type ; cf. le tableau précédent. Quand cet attribut est défini avec la valeur null, son paramétrage ne produit aucun effet y compris quand le nœud est en lecture seule.
Exception à l'initialisation

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule.

Exceptions en retour

DOMException

DOMSTRING_SIZE_ERR : Soulevée si cela devait retourner plus de caractères qu'un objet DOMString peut contenir, variable selon la plateforme de la mise en œuvre.

ownerDocument de type Document, en lecture seule, modifié dans DOM niveau 2
L'objet Document associé à ce nœud. C'est aussi l'objet Document utilisé pour créer de nouveaux nœuds. Quand ce nœud est un objet Document, ou DocumentType, qui n'est pas encore utilisé avec un objet Document, la valeur null est retournée.
parentNode de type Node, en lecture seule
Le parent de ce nœud. Tous les nœuds, sauf Attr, Document, DocumentFragment, Entity et Notation, peuvent avoir un parent. Cependant, si ce nœud vient juste d'être créé et n'est pas encore ajouté à l'arbre, ou si ce nœud a été retiré de l'arbre, la valeur null est retournée.
prefix de type DOMString, introduit dans DOM niveau 2
Le préfixe d'espace de nommage de ce nœud, ou la valeur null si non indiqué.
Remarquer que le paramétrage de cet attribut, quand cela est permis, change l'attribut nodeName, qui contient le nom qualifié, tout comme les attributs tagName et name des interfaces Element et Attr, quand celles-ci s'appliquent.
Remarquer également que le changement du préfixe d'un attribut dont on sait qu'il a une valeur par défaut ne fait pas apparaître un nouvel attribut avec la valeur par défaut et le préfixe original, car les attributs namespaceURI et localName ne changent pas.
Pour les nœuds de tout autre type que ELEMENT_NODE ou ATTRIBUTE_NODE et pour les nœuds créés par une méthode DOM niveau 1, telle que la méthode createElement de l'interface Document, la valeur null est toujours retournée.
Exception à l'initialisation

DOMException

INVALID_CHARACTER_ERR : Soulevée si le préfixe indiqué contient un caractère illégal selon la spécification XML 1.0 [XML].

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

NAMESPACE_ERR : Soulevée si le préfixe indiqué est malformé selon la spécification des espaces de nommage dans XML, ou si l'attribut namespaceURI de ce nœud a la valeur null, ou si le préfixe indiqué est "xml" et la valeur de l'attribut namespaceURI de ce nœud est différente de "http://www.w3.org/XML/1998/namespace", ou si ce nœud est un attribut, le préfixe indiqué est "xmlns" et l'attribut namespaceURI de ce nœud est différent de "http://www.w3.org/2000/xmlns/", ou si ce nœud est un attribut et la valeur de qualifiedName de ce nœud est "xmlns" [Les espaces de nommage].

previousSibling de type Node, en lecture seule
Le nœud qui précède immédiatement ce nœud. S'il n'y a pas un tel nœud, retourne la valeur null.
Méthodes
appendChild
Ajoute le nœud newChild à la fin de la liste des enfants de ce nœud. Si newChild est déjà dans l'arbre, il en est d'abord retiré.
Paramètres
newChild de type Node
Le nœud à ajouter.
Si c'est un objet DocumentFragment, le contenu entier du fragment de document est transféré dans la liste enfant de ce nœud.
Valeur retournée

Node

Le nœud ajouté.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfant du type de ce nœud newChild, ou si le nœud à ajouter à la suite est un des ancêtres de ce nœud ou ce nœud en question.

WRONG_DOCUMENT_ERR : Soulevée si le nœud newChild a été créé à partir d'un document différent de celui qui a créé le nœud en question.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule ou si le parent précédent du nœud à insérer est en lecture seule.

cloneNode
Retourne un double de ce nœud, c.à.d., fait office de constructeur de copie générique pour les nœuds. Le nœud copié n'a pas de parent (parentNode a une valeur de null).
Le clonage d'un objet Element recopie tous les attributs et leurs valeurs, y compris ceux générés par le processeur XML pour représenter les attributs implicites ; toutefois, cette méthode ne recopie pas le texte qui y est contenu, à moins qu'il ne s'agisse d'un clone en profondeur, puisque le texte est contenu dans un nœud Text enfant. Le clonage direct d'un objet Attribute, contrairement au clonage partiel d'un objet Element, retourne un attribut spécifié (specified a la valeur true). Le clonage de tout autre type de nœud retourne simplement une copie du nœud.
Remarquer que le clonage d'un sous-arbre immuable produit une copie mutable ; toutefois, les enfants du clone d'un objet EntityReference sont en lecture seule. En outre, les clones de nœuds Attr non spécifiés sont indiqués. Le clonage de nœuds Document, DocumentType, Entity et Notation dépend également de la mise en œuvre.
Paramètres
deep de type boolean
Pour la valeur true, clone récursivement le sous-arbre à partir du nœud indiqué ; pour la valeur false, ne clone que le nœud en question (et ses attributs, si c'est un nœud Element).
Valeur retournée

Node

Le nœud en double.

Aucune exception
hasAttributes introduit dans DOM niveau 2
Indique si ce nœud (quand c'est un Element) a des attributs, ou non .
Valeur retournée

boolean

true si ce nœud a un attribut, false sinon.

Aucun paramètre
Aucune exception
hasChildNodes
Indique si ce nœud a des enfants, ou non.
Valeur retournée

boolean

true si ce nœud a un enfant, false sinon.

Aucun paramètre
Aucune exception
insertBefore
Insère le nœud newChild avant le nœud refChild existant. Si refChild est null, insère newChild à la fin de la liste des enfants.
Si newChild est un objet DocumentFragment, tous ses enfants sont insérés, dans le même ordre, avant refChild. Si le nœud newChild est déjà dans l'arbre, il en est d'abord retiré.
Paramètres
newChild de type Node
Le nœud à insérer.
refChild de type Node
Le nœud de référence, c.à.d., le nœud avant lequel le nouveau doit être inséré.
Valeur retournée

Node

Le nœud à insérer.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfants du type du nœud newChild, ou si le nœud à insérer est l'un des ancêtres de ce nœud ou ce nœud en question.

WRONG_DOCUMENT_ERR : Soulevée si newChild a été créé à partir d'un document différent de celui qui a créé ce nœud en question.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud ou si le parent du nœud à insérer sont en lecture seule.

NOT_FOUND_ERR : Soulevée si refChild n'est pas un enfant de ce nœud.

isSupported introduit dans DOM niveau 2
Teste si l'application DOM met en œuvre ou non une fonction spécifique et que celle-ci est gérée par ce nœud.
Paramètres
feature de type DOMString
Le nom de la fonction à tester. C'est le même nom qui peut être passé à la méthode hasFeature de l'interface DOMImplementation.
version de type DOMString
C'est le numéro de version de la fonction à tester. Pour le DOM niveau 2, première édition, c'est la chaîne "2.0". Si la version n'est pas indiquée, toutes les versions de la fonction sont gérées, et la méthode retourne la valeur true.
Valeur retournée

boolean

Retourne la valeur true si la fonction indiquée est gérée par ce nœud, sinon la valeur false.

Aucune exception
normalize modifié dans DOM niveau 2
Place tous les nœuds Text dans la profondeur entière du sous-arbre en aval de ce Node, y compris les nœuds attributs, dans une forme normale où seule la structure (par exemple, les éléments, les commentaires, les instructions de traitement, les sections CDATA et les appels d'entité) distingue les nœuds Text, c.à.d. qu'il n'y a pas de nœuds Text adjacents ni de nœuds Text vides. On peut s'en servir pour s'assurer que la vue DOM d'un document est identique comme si celui-ci avait été stocké puis rechargé ; elle est utile quand on doit effectuer des opérations (comme les recherches XPointer [XPointer]) qui dépendent de la structure d'arbre d'un document particulier.

Remarque : Pour les cas où le document contient des nœuds CDATASection, l'opération de normalisation seule sera peut-être insuffisante, puisque les pointeur XPointer ne font aucune différence entre les nœuds Text et CDATASection.

Aucun paramètre
Aucune valeur retournée
Aucune exception
removeChild
Retire le nœud enfant désigné par oldChild de la liste des enfants et retourne ce nœud.
Paramètres
oldChild de type Node
Le nœud à retirer.
Valeur retournée

Node

Le nœud retiré.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

NOT_FOUND_ERR : Soulevée si oldChild n'est pas un enfant de ce nœud.

replaceChild
Remplace le nœud enfant oldChild par newChild dans la liste des enfants et retourne le nœud oldChild.
Si newChild est un objet DocumentFragment, le nœud oldChild est remplacé par tous les enfants de DocumentFragment, qui sont insérés dans le même ordre. Si le nœud newChild est déjà dans l'arbre, il en est d'abord retiré.
Paramètres
newChild de type Node
Le nouveau nœud à placer dans la liste enfant.
oldChild de type Node
Le nœud qui est remplacé dans la liste.
Valeur retournée

Node

Le nœud remplacé.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR : Soulevée si ce nœud est d'un type qui n'admet pas d'enfant du type du nœud newChild, ou si le nœud à remplacer est l'un des ancêtres de ce nœud ou ce nœud en question.

WRONG_DOCUMENT_ERR : Soulevée si newChild a été créé à partir d'un document différent de celui qui a créé ce nœud.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud ou le parent du nouveau nœud sont en lecture seule.

NOT_FOUND_ERR : Soulevée si oldChild n'est pas un enfant de ce nœud.

L'interface NodeList

L'interface NodeList fournit une abstraction d'une collection de nœuds ordonnée, sans définir ni contraindre la façon dont elle est mise en œuvre. Les objets NodeList dans le DOM sont vivants.

Les articles dans l'objet NodeList sont accessibles via un index de nombre entier, commençant par 0.


Définition IDL
interface NodeList {
  Node               item(in unsigned long index);
  readonly attribute unsigned long    length;
};

Attributs
length de type unsigned long, en lecture seule
Le nombre de nœuds dans la liste. L'index des nœuds enfants valides s'étend de 0 à length-1 inclus.
Méthodes
item
Retourne l'index de l'article dans la collection. Si index est supérieur ou égal au nombre de nœuds dans la liste, retourne la valeur null.
Paramètres
index of type unsigned long
L'index dans la collection.
Valeur retournée

Node

Le nœud à la position indiquée par index dans l'objet NodeList, ou la valeur null si ce n'est pas un index valide.

Aucune exception
L'interface NamedNodeMap

Les objets qui mettent en œuvre l'interface NamedNodeMap sont employés pour représenter des collections de nœuds auxquels on accède par leur nom. Remarquer que NamedNodeMap n'hérite pas de NodeList ; les objets NamedNodeMap ne sont pas conservés dans un ordre particulier. On peut aussi accéder aux objets contenus dans un objet mettant en œuvre NamedNodeMap par un index ordinal mais simplement pour permettre une énumération pratique du contenu d'un objet NamedNodeMap, et cela n'implique pas que le DOM déninisse un ordre pour ces nœuds.

Les objets NamedNodeMap dans le DOM sont vivants.


Définition IDL
interface NamedNodeMap {
  Node               getNamedItem(in DOMString name);
  Node               setNamedItem(in Node arg)
                                        raises(DOMException);
  Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
  Node               item(in unsigned long index);
  readonly attribute unsigned long    length;
  // Introduite dans DOM niveau 2 :
  Node               getNamedItemNS(in DOMString namespaceURI, 
                                    in DOMString localName);
  // Introduite dans DOM niveau 2 :
  Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  Node               removeNamedItemNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
};

Attributs
length de type unsigned long, en lecture seule
Le nombre de nœuds dans cette carte. L'index des nœuds enfants valides s'étend de 0 à length-1 inclus.
Méthodes
getNamedItem
Récupère un nœud indiqué par son nom.
Paramètres
name de type DOMString
La valeur nodeName d'un nœud à récupérer.
Valeur retournée

Node

Un objet Node (quel que soit le type) avec la valeur nodeName indiquée, ou la valeur null si le paramètre n'identifie aucun nœud dans cette carte.

Aucune exception
getNamedItemNS introduit dans DOM niveau 2
Récupère un nœud indiqué par un nom local et une adresse URI d'espace de nommage. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage du nœud à récupérer.
localName de type DOMString
Le nom local du nœud à récupérer.
Valeur retournée

Node

Un objet Node (quel que soit le type) avec le nom local et l'adresse URI d'espace de nommage indiqués, ou la valeur null si ces paramètres n'identifient aucun nœud dans cette carte.

Aucune exception
Exception

DOMException

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

item
Retourne la valeur du paramètre index de l'item dans la carte. Si index est supérieur ou égal au nombre de nœuds dans cette carte, la méthode retourne null.
Paramètres
index de type unsigned long
Un index dans cette carte.
Valeur retournée

Node

Le nœud dont la position dans la carte est indiquée par le paramètre index, ou la valeur null si l'index n'est pas valide.

Aucune exception
removeNamedItem
Retire un nœud indiqué par son nom. Quand cette carte contient les attributs liés à un élément, si c'est un attribut retiré dont on sait qu'il a une valeur par défaut, alors il apparaît immédiatement un attribut contenant la valeur par défaut et, le cas échéant, l'adresse URI d'espace de nommage, le nom local et le préfixe correspondants.
Paramètres
name de type DOMString
L'attribut nodeName du nœud à retirer.
Valeur retournée

Node

Le nœud retiré de cette carte, s'il en existe un avec ce nom.

Exceptions

DOMException

NOT_FOUND_ERR : Soulevée si aucun nœud ne correspond au nom du paramètre name dans la carte.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule.

removeNamedItemNS introduit dans DOM niveau 2
Retire un nœud indiqué par un nom local et une adresse URI d'espace de nommage. On peut savoir si un attribut retiré a une valeur par défaut quand cette carte contient les attributs liés à un élément, tels qu'ils sont retourné par l'attribut attributes de l'interface Node. Auquel cas, il apparaît immédiatement un attribut contenant la valeur par défaut et, le cas échéant, l'adresse URI d'espace de nommage, le nom local et le préfixe correspondants.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage du nœud à retirer.
localName de type DOMString
Le nom local du nœud à retirer.
Valeur retournée

Node

Le nœud retiré de cette carte, s'il en existe un avec ce nom local et cette adresse URI d'espace de nommage.

Exceptions

DOMException

NOT_FOUND_ERR : Soulevée s'il n'existe aucun nœud correspondant aux paramètres namespaceURI et localName dans cette carte.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

setNamedItem
Ajoute un nœud en utilisant son attribut nodeName. Si un nœud avec ce nom est déjà présent dans cette carte, il est remplacé par le nouveau.
Le remplacement d'un nœud d'attribut par lui-même n'a aucun effet.
Comme l'attribut nodeName est utilisé pour dériver le nom sous lequel le nœud devra être stocké, on ne peut pas stocker plusieurs nœuds ayant certains types (ceux qui ont une valeur de chaîne spéciale) car les noms peuvent entrer en conflit. Il semble préférable de recourir à cette solution plutôt qu'à des alias pour les nœuds.
errata : 2002-02-14
Paramètres
arg de type Node
Un nœud à stocker dans cette carte. On pourra accéder au nœud plus tard en utilisant la valeur de son attribut nodeName.
Valeur retournée

Node

Si le nouveau Node remplace un nœud existant, c'est le Node remplacé qui est retourné, sinon la valeur null.

Exceptions

DOMException

WRONG_DOCUMENT_ERR : Soulevée si le paramètre arg a été créé à partir d'un document différent de celui qui a créé cette carte.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule.

INUSE_ATTRIBUTE_ERR : Soulevée si arg est un objet Attr qui est déjà l'attribut d'un autre objet Element. L'utilisateur du DOM doit cloner explicitement les nœuds Attr pour les réutiliser dans d'autres éléments.

HIERARCHY_REQUEST_ERR : Soulevée pour une tentative d'ajout d'un nœud qui n'appartient pas à cet objet NamedNodeMap. Comme exemples, une tentative d'insérer autre chose qu'un nœud Attr dans la carte des attributs d'un objet Element ou d'insérer autre chose qu'un nœud Entity dans la carte des objets Entity d'un objet DocumentType.

setNamedItemNS introduit dans DOM niveau 2
Ajoute un nœud en utilisant ses attributs namespaceURI et localName. Si un nœud avec cette adresse URI d'espace de nommage et ce nom local est déjà présent dans cette carte, il est remplacé par le nouveau.
Le remplacement d'un nœud d'attribut par lui-même n'a aucun effet.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

errata : 2002-02-14
Paramètres
arg de type Node
Un nœud à stocker dans cette carte. On pourra y accéder plus tard en utilisant ses attributs namespaceURI et localName.
Valeur retournée

Node

Si le nouveau Node remplace un nœud existant, retourne le Node remplacé, sinon la valeur null.

Exceptions

DOMException

WRONG_DOCUMENT_ERR : Soulevée si le paramètre arg a été créé à partir d'un document différent de celui qui a créé cette carte.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si cette carte est en lecture seule.

INUSE_ATTRIBUTE_ERR : Soulevée si arg est un objet Attr qui est déjà un attribut d'un autre objet Element. L'utilisateur du DOM doit cloner explicitement les nœuds Attr pour les réutiliser dans d'autres éléments.

HIERARCHY_REQUEST_ERR : Soulevée pour une tentative d'ajout d'un nœud qui n'appartient pas à cet objet NamedNodeMap. Comme exemples, une tentative d'insérer autre chose qu'un nœud Attr dans la carte des attributs d'un objet Element ou d'insérer autre chose qu'un nœud Entity dans la carte des objets Entity d'un objet DocumentType.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

L'interface CharacterData

L'interface CharacterData renforce l'objet Node par un jeu d'attributs et de méthodes afin d'accéder aux données textuelles dans le DOM. Pour la lisibilité, on définit ce jeu ici plutôt que dans chaque objet utilisant ces attributs et méthodes. Aucun objet DOM ne correspond directement à un nœud CharacterData, quoique les nœuds Text et d'autres héritent de son interface. Tous les paramètres offset dans cette interface se détermine par rapport à 0.

Comme expliqué dans l'interface DOMString, les chaînes textuelles dans le DOM sont représentées dans un codage UTF-16, c.à.d., comme une séquence d'unités de 16 bits. Par la suite, on emploiera le terme unités de 16 bits, à chaque fois que c'est nécessaire, pour indiquer que l'indexation des objets CharacterData a lieu selon des unités de 16 bits.


Définition IDL
interface CharacterData : Node {
           attribute DOMString        data;
                                // soulève une exception DOMException à l'initialisation
                                // soulève une exception DOMException en retour

  readonly attribute unsigned long    length;
  DOMString          substringData(in unsigned long offset, 
                                   in unsigned long count)
                                        raises(DOMException);
  void               appendData(in DOMString arg)
                                        raises(DOMException);
  void               insertData(in unsigned long offset, 
                                in DOMString arg)
                                        raises(DOMException);
  void               deleteData(in unsigned long offset, 
                                in unsigned long count)
                                        raises(DOMException);
  void               replaceData(in unsigned long offset, 
                                 in unsigned long count, 
                                 in DOMString arg)
                                        raises(DOMException);
};

Attributs
data de type DOMString
Les données textuelles du nœud qui mettent en œuvre cette interface. La mise en œuvre DOM ne doit pas fixer de limites arbitraires à la quantité des données stockables dans un nœud CharacterData. Néanmoins, les limitations de la mise en œuvre empêcheront peut-être que la totalité des données d'un nœud puisse tenir dans un objet DOMString. Auquel cas, l'utilisateur peut appeler la méthode substringData pour récupérer les données par morceaux de dimension appropriée.
Exception à l'initialisation

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule.

Exceptions en retour

DOMException

DOMSTRING_SIZE_ERR : Soulevée si cela devait retourner plus de caractères qu'un objet DOMString peut en contenir, variable selon la plateforme de la mise en œuvre.

length de type unsigned long, en lecture seule
Le nombre d'unités de 16 bits qui sont disponibles au travers de l'attribut data et de la méthode substringData suivante. Cette valeur peut être nulle, c.à.d. que les nœuds CharacterData peuvent être vides.
Méthodes
appendData
Ajoute la chaîne à la fin des donnés textuelles du nœud. En cas de succès, l'attribut data offre un accès à la concaténation de data et de l'objet DOMString indiqué.
Paramètres
arg de type DOMString
L'objet DOMString à ajouter.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
deleteData
Supprime une certaine étendue d'unités de 16 bits du nœud. En cas de succès les attributs data et length reflètent ce changement.
Paramètres
offset of type unsigned long
Le décalage à partir duquel commencer le retrait.
count of type unsigned long
Le nombre d'unités de 16 bits à supprimer. Si la somme des valeurs des paramètres offset et count excède la valeur de l'attribut length, alors toutes les unités de 16 bits, en partant de la position de décalage jusqu'au bout des données, sont supprimées.
Exceptions

DOMException

INDEX_SIZE_ERR : Soulevée si le paramètre offset indiqué est négatif ou supérieur au nombre d'unités de 16 bits dans l'attribut data, ou si le paramètre count indiqué est négatif.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
insertData
Insère une chaîne à la position de décalage indiquée, exprimée en unité de 16 bits.
Paramètres
offset de type unsigned long
Le décalage de caractère où effectuer l'insertion.
arg de type DOMString
L'objet DOMString à insérer.
Exceptions

DOMException

INDEX_SIZE_ERR : Soulevée si le paramètre offset indiqué est négatif ou supérieur au nombre d'unités de 16 bits dans l'attribut data

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
replaceData
Remplace les caractères depuis la position de décalage exprimée en unités de 16 bits par la chaîne indiquée.
Paramètres
offset de type unsigned long
La position de décalage où le remplacement commence.
count de type unsigned long
Le nombre d'unités de 16 bits à remplacer. Si la somme des paramètres offset et count excède la valeur de l'attribut length, alors toutes les unités de 16 bits jusqu'au bout des données sont remplacées (c.à.d., l'effet produit est identique à celui de l'appel de la méthode remove pour une même étendue suivi d'une invocation de la méthode append).
arg de type DOMString
L'objet DOMString qui doit remplacer l'étendue de texte.
Exceptions

DOMException

INDEX_SIZE_ERR : Soulevée si le paramètre offset indiqué est négatif ou supérieur au nombre d'unités de 16 bits dans l'attribut data, ou si le paramètre count indiqué est négatif.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
substringData
Extrait une étendue de données du nœud.
Paramètres
offset de type unsigned long
Décalage à partir duquel extraire la sous-chaîne.
count de type unsigned long
Le nombre d'unités de 16 bits à extraire.
Valeur retournée

DOMString

La sous-chaîne indiquée. Si la somme des paramètres offset et count excède la valeur de l'attribut length, alors toutes les unités de 16 bits jusqu'à la fin des données sont retournées.

Exceptions

DOMException

INDEX_SIZE_ERR : Soulevée si le paramètre offset indiqué est négatif ou supérieur au nombre d'unités de 16 bits dans l'attribut data, ou si le paramètre count indiqué est négatif.

DOMSTRING_SIZE_ERR : Soulevée si l'étendue de texte indiquée ne tient pas dans un objet DOMString.

L'interface Attr

L'interface Attr représente un attribut dans un objet Element. Les valeurs admises pour l'attribut sont typiquement définies dans la définition de type de document.

Les objets Attr héritent de l'interface Node mais, puisque ceux-ci ne sont pas effectivement des nœuds enfants de l'élément qu'ils décrivent, le DOM ne les considère pas comme faisant partie de l'arbre du document. Les attributs parentNode, previousSibling et nextSibling d'un objet Node ont donc une valeur null pour les objets Attr. Le DOM voit les attributs comme des propriétés d'éléments plutôt que comme ayant une identité distincte des éléments auxquels ils sont associés ; ceci devrait permettre une mise en œuvre plus efficace de caractéristiques telles que les valeurs par défaut des attributs associées à tous les éléments d'un type donné. En outre, les nœuds Attr ne peuvent pas être les enfants immédiats d'un objet DocumentFragment. Par contre, on peut les associer aux nœuds Element contenus dans un objet DocumentFragment. En bref, les utilisateurs et développeurs DOM doivent savoir que les nœuds Attr ont des points communs avec les autres objets héritant de l'interface Node mais ils s'en distinguent aussi beaucoup.

La valeur effective de l'attribut se détermine de la manière suivante : si la valeur est affectée explicitement, alors c'est sa valeur effective ; sinon, s'il existe une déclaration de cet attribut avec une valeur par défaut, alors c'est sa valeur effective ; sinon l'attribut n'existe pas sur l'élément dans le modèle de structure tant qu'on ne l'a pas ajouté explicitement. Remarquer qu'on peut aussi utiliser l'attribut nodeValue sur l'instance Attr pour récupérer la version littérale de la valeur, ou des valeurs, de l'attribut.

En XML, où la valeur d'un attribut peut contenir des appels d'entité, les nœuds enfants du nœud Attr peuvent contenir soit des nœuds Text, soit des nœuds EntityReference (lorsqu'ils sont utilisés ; cf. EntityReference pour une explication). Comme DOM Core ignore le type des attributs, toutes les valeurs d'attribut sont traitées comme de simples chaînes, même si la définition de type de document (DTD), ou le schéma, les déclare comme étant d'un type atomique.


Définition IDL
interface Attr : Node {
  readonly attribute DOMString        name;
  readonly attribute boolean          specified;
           attribute DOMString        value;
                                 // soulève une exception DOMException à l'initialisation

  // Introduite dans DOM niveau 2 :
  readonly attribute Element          ownerElement;
};

Attributs
name de type DOMString, en lecture seule
Retourne le nom de cet attribut.
ownerElement de type Element, en lecture seule, introduit dans DOM niveau 2
Le nœud Element auquel cet attribut est lié, sinon la valeur null quand l'attribut n'est pas utilisé.
specified de type boolean, en lecture seule
Si cet attribut a reçu explicitement une valeur dans le document original, prend la valeur true ; sinon, la valeur false. Remarquer que c'est la mise en œuvre qui prend en charge cet attribut, non l'utilisateur. Si l'utilisateur change la valeur de l'attribut (même si cela revient à avoir une valeur identique à la valeur par défaut), alors le drapeau specified se met automatiquement à true. Pour redéfinir l'attribut avec la valeur par défaut de la définition de type de document (DTD), l'utilisateur doit supprimer l'attribut. La mise en œuvre disposera alors un nouvel attribut, avec specified mis à false et la valeur par défaut (s'il y en a une).
En résumé :
  • Si on assigne une valeur à l'attribut dans le document, alors specified vaut true et l'attribut a cette valeur assignée ;
  • Si on n'assigne aucune valeur à l'attribut dans le document et que le DTD définit une valeur par défaut, alors specified vaut false et l'attribut prend cette valeur par défaut du DTD ;
  • Si on n'assigne aucune valeur à l'attribut dans le document et que le DTD définit comme valeur #IMPLIED, alors l'attribut n'apparaît pas dans le modèle de structure du document ;
  • Si la valeur de l'attribut ownerElement vaut null (c.à.d., que l'attribut vient tout juste d'être créé ou qu'il ait été mis à null par des opérations de retrait ou de clonage diverses), alors specified vaut true.

value de type DOMString
En retour, la valeur de l'attribut prend la forme d'une chaîne. Les appels de caractères et d'entités générales sont remplacés par leur valeur. Voir également la méthode getAttribute sur l'interface Element.
À l'initialisation, un nœud Text est créé avec le contenu non analysé de la chaîne. C'est-à-dire que tous les caractères qu'un processeur XML reconnaîtrait comme du balisage sont traités à la place comme du texte littéral. Voir également la méthode setAttribute sur l'interface Element.
Exception à l'initialisation

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule.

L'interface Element

L'interface Element représente un élément dans un document HTML ou XML. Les éléments peuvent avoir des attributs associés ; comme l'interface Element hérite de celle de Node, on peut utiliser l'attribut générique attributes de l'interface Node pour récupérer le jeu de tous les attributs d'un élément. L'interface Element possède des méthodes pour récupérer par leur nom soit un objet Attr, soit une valeur d'attribut. En XML, où une valeur d'attribut peut contenir des appels d'entité, on devrait récupérer un objet Attr pour examiner le sous-arbre, qui peut être très complexe, représentant la valeur d'attribut. En ce qui concerne HTML, où tous les attributs ont des valeurs de chaîne simples, on peut utiliser par commodité les méthodes d'accès direct à la valeur d'attribut en toute sécurité.

Remarque : Dans DOM niveau 2, la méthode normalize est héritée de l'interface Node dans laquelle cette méthode a été déplacé.


Définition IDL
interface Element : Node {
  readonly attribute DOMString        tagName;
  DOMString          getAttribute(in DOMString name);
  void               setAttribute(in DOMString name, 
                                  in DOMString value)
                                        raises(DOMException);
  void               removeAttribute(in DOMString name)
                                        raises(DOMException);
  Attr               getAttributeNode(in DOMString name);
  Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
  Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString name);
  // Introduite dans DOM niveau 2 :
  DOMString          getAttributeNS(in DOMString namespaceURI, 
                                    in DOMString localName);
  // Introduite dans DOM niveau 2 :
  void               setAttributeNS(in DOMString namespaceURI, 
                                    in DOMString qualifiedName, 
                                    in DOMString value)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  void               removeAttributeNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  Attr               getAttributeNodeNS(in DOMString namespaceURI, 
                                        in DOMString localName);
  // Introduite dans DOM niveau 2 :
  Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
  // Introduite dans DOM niveau 2 :
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI, 
                                            in DOMString localName);
  // Introduite dans DOM niveau 2 :
  boolean            hasAttribute(in DOMString name);
  // Introduite dans DOM niveau 2 :
  boolean            hasAttributeNS(in DOMString namespaceURI, 
                                    in DOMString localName);
};

Attributs
tagName de type DOMString, en lecture seule
Le nom de l'élément. Par exemple, dans :
<elementExemple id="demo"> 
        ... 
</elementExemple> ,
L'attribut tagName a la valeur "elementExemple". Remarquer que la casse est préservée en XML comme dans toutes les opérations DOM. Le DOM HTML retourne l'attribut tagName d'un élément HTML dans une forme canonique en majuscules, quelle que soit la casse dans le document HTML source.
Méthodes
getAttribute
Récupère une valeur d'attribut par son nom.
Paramètres
name de type DOMString
Le nom de l'attribut à récupérer.
Valeur retournée

DOMString

La valeur de l'objet Attr sous forme de chaîne, ou la chaîne vide si cet attribut n'a pas de valeur indiquée ou de valeur par défaut.

Aucune exception
getAttributeNS introduit dans DOM niveau 2
Récupère une valeur d'attribut par son nom local et son adresse URI d'espace de nommage. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à récupérer.
localName de type DOMString
Le nom local de l'attribut à récupérer.
Valeur retournée

DOMString

La valeur de l'objet Attr sous forme de chaîne, ou la chaîne vide si cet attribut n'a pas de valeur indiquée ou de valeur par défaut.

Aucune exception
Exception

DOMException

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

getAttributeNode
Récupère un nœud d'attribut par son nom.
Pour récupérer un nœud d'attribut par son nom qualifié et son adresse URI d'espace de nommage, utiliser la méthode getAttributeNodeNS.
Paramètres
name de type DOMString
Le nom (nodeName) de l'attribut à récupérer.
Valeur retournée

Attr

Le nœud Attr avec le nom indiqué (nodeName), ou la valeur null s'il n'y a pas un tel attribut.

Aucune exception
getAttributeNodeNS introduit dans DOM niveau 2
Récupère un nœud Attr par son nom local et son adresse URI d'espace de nommage. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à récupérer.
localName de type DOMString
Le nom local de l'attribut à récupérer.
Valeur retournée

Attr

Le nœud Attr avec le nom local et l'adresse URI d'espace de nommage de l'attribut indiqué, ou la valeur null s'il n'y a pas un tel attribut.

Aucune exception
Exception

DOMException

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

getElementsByTagName
Retourne un objet NodeList de tous les nœuds Element descendants avec le nom de balise donné, dans l'ordre où ils sont rencontrés dans la traversée préordonnée de l'arbre de cet Element.
Paramètres
name de type DOMString
Le nom de la balise à rechercher. La valeur spéciale "*" correspond à toutes les balises.
Valeur retournée

NodeList

Une liste de nœuds Element correspondants.

Aucune exception
getElementsByTagNameNS introduit dans DOM niveau 2
Retourne un objet NodeList de tous les nœuds Element descendants avec un nom local et une adresse URI d'espace de nommage donné, dans l'ordre où ils sont rencontrés dans la traversée préordonnée de l'arbre de cet Element.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.
Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage des éléments à rechercher. La valeur spéciale "*" correspond à tous les espaces de nommage.
localName de type DOMString
Le nom local des éléments à rechercher. La valeur spéciale "*" correspond à tous les noms locaux.
Valeur retournée

NodeList

Un nouvel objet NodeList contenant tous les nœuds Element trouvés.

Aucune exception
hasAttribute introduit dans DOM niveau 2
Retourne la valeur true quand un attribut avec un nom donné est indiqué sur cet élément ou quand l'attribut a une valeur par défaut, sinon la valeur false.
Paramètres
name de type DOMString
Le nom de l'attribut à rechercher.
Valeur retournée

boolean

La valeur true si un attribut avec le nom donné est indiqué sur cet élément ou si l'attribut a une valeur par défaut, sinon la valeur false.

Aucune exception
hasAttributeNS introduit dans DOM niveau 2
Retourne la valeur true quand un attribut avec un nom local et une adresse URI d'espace de nommage donnés ou quand l'attribut a une valeur par défaut, sinon la valeur false. Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à rechercher.
localName de type DOMString
Le nom local de l'attribut à rechercher.
Valeur retournée

boolean

La valeur true si un attribut avec le nom local et l'adresse URI d'espace de nommage donnés est indiqué sur cet élément ou si l'attribut a une valeur par défaut, sinon la valeur false.

Aucune exception
Exception

DOMException

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

removeAttribute
Retire un attribut par son nom. Si c'est un attribut retiré dont on sait qu'il a une valeur par défaut, alors il apparaît immédiatement un attribut contenant la valeur par défaut et, le cas échéant, l'adresse URI d'espace de nommage, le nom local et le préfixe correspondants.
Pour retirer un attribut par son nom local et son adresse URI d'espace de nommage, utiliser la méthode removeAttributeNS. Si l'attribut n'a pas de valeur indiquée ni de valeur par défaut, l'appel de cette méthode ne produit aucun effet.
Paramètres
name de type DOMString
Le nom de l'attribut à retirer.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
removeAttributeNS introduit dans DOM niveau 2
Retire un attribut par son nom local et son adresse URI d'espace de nommage. Si l'attribut retiré a une valeur par défaut, il est immédiatement remplacé. L'attribut remplaçant a les mêmes adresse URI d'espace de nommage, nom local et préfixe que l'original.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

errata : 2001-08-31
Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à retirer.
localName de type DOMString
Le nom local de l'attribut à remplacer.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

Aucune valeur retournée
removeAttributeNode
Retire le nœud attribut indiqué. Si l'objet Attr retiré a une valeur par défaut, il est immédiatement remplacé. L'attribut remplaçant a les mêmes adresse URI d'espace de nommage, nom local et, le cas échéant, préfixe que l'original.
Paramètres
oldAttr de type Attr
Le nœud Attr à retirer de la liste d'attributs.
Valeur retournée

Attr

Le nœud Attr qui est retiré.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

NOT_FOUND_ERR : Soulevée si oldAttr n'est pas un attribut de l'élément.

setAttribute
Ajoute un nouvel attribut. Si un attribut avec ce nom est déjà présent dans l'élément, sa valeur est changée par celle du paramètre value. Cette valeur est une simple chaîne qui n'est pas analysée lors de l'initialisation. Tout balisage (comme toute syntaxe devant représenter un appel d'entité) sera donc traité comme du texte littéral et nécessitera un masquage adéquat par la mise en œuvre lors de son écriture. Pour affecter une valeur contenant des appels d'entité à un attribut, l'utilisateur doit créer un nœud Attr et tous les nœuds Text et EntityReference nécessaires, construire le sous-arbre approprié et utiliser la méthode setAttributeNode pour l'affecter comme valeur d'attribut.
Pour initialiser un attribut avec un nom qualifié et une adresse URI d'espace de nommage, utiliser la méthode setAttributeNS.
Paramètres
name de type DOMString
Le nom de l'attribut à créer ou à modifier.
value de type DOMString
La valeur sous forme de chaîne à assigner.
Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom indiqué contient un caractère illégal.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

Aucune valeur retournée
setAttributeNS introduit dans DOM niveau 2
Ajoute un nouvel attribut. Si un attribut avec les mêmes nom local et adresse URI d'espace de nommage est déjà présent sur l'élément, son préfixe est changé pour la partie préfixe de l'attribut qualifiedName et sa valeur est pour celle du paramètre value. Cette valeur est une simple chaîne qui n'est pas analysée lors de l'initialisation. Tout balisage (comme toute syntaxe devant être reconnue comme un appel d'entité) sera donc traité comme du texte littéral et nécessitera un masquage adéquat par la mise en œuvre lors de son écriture. Pour affecter une valeur d'attribut contenant des appels d'entité à un attribut, l'utilisateur doit créer un nœud Attr et tous les nœuds Text et EntityReference nécessaires, construire le sous-arbre approprié et utiliser la méthode setAttributeNodeNS, ou setAttributeNode, pour l'assigner comme valeur de l'attribut.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

Paramètres
namespaceURI de type DOMString
L'adresse URI d'espace de nommage de l'attribut à créer ou à modifier.
qualifiedName de type DOMString
Le nom qualifié de l'attribut à créer ou à modifier.
value de type DOMString
La valeur sous forme de chaîne à assigner.
Exceptions

DOMException

INVALID_CHARACTER_ERR : Soulevée si le nom qualifié indiqué contient un caractère illégal selon la spécification XML 1.0 [XML].

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

NAMESPACE_ERR : Soulevée si qualifiedName est malformé selon la spécification des espaces de nommage dans XML, ou si qualifiedName a un préfixe et namespaceURI est null, ou si qualifiedName a un préfixe qui est "xml" et namespaceURI est différent de "http://www.w3.org/XML/1998/namespace", ou si qualifiedName (ou son préfixe) est "xmlns" et namespaceURI est différent de "http://www.w3.org/2000/xmlns/".

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

Aucune valeur retournée
setAttributeNode
Ajoute un nouveau nœud attribut. Si un attribut avec ce nom (nodeName) est déjà présent dans l'élément, il est remplacé par le nouveau.
Pour ajouter un nouveau nœud attribut avec un nom qualifié et une adresse URI d'espace de nommage, utiliser la méthode setAttributeNodeNS. Le remplacement d'un nœud d'attribut par lui-même n'a aucun effet.
Paramètres
newAttr de type Attr
Le nœud Attr lequel ajouter à la liste d'attributs.
Valeur retournée

Attr

Si l'attribut newAttr remplace un attribut existant, le nœud Attr remplacé est retourné, sinon la valeur null.

Exceptions

DOMException

WRONG_DOCUMENT_ERR : Soulevée si newAttr a été créé à partir d'un document différent de celui qui a créé l'élément.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

INUSE_ATTRIBUTE_ERR : Soulevée si newAttr est déjà l'attribut d'un autre objet Element. L'utilisateur du DOM doit cloner explicitement les nœuds Attr pour leur réutilisation dans d'autres éléments.

setAttributeNodeNS introduit dans DOM niveau 2
Ajoute un nouvel attribut. Si un attribut avec ce nom local et cette adresse URI d'espace de nommage est déjà présent dans l'élément, il est remplacé par le nouveau.
Le remplacement d'un nœud d'attribut par lui-même n'a aucun effet.
Les mises en œuvre DOM seulement HTML ne sont pas tenues de mettre en œuvre cette méthode.

Selon [Les espaces de nommage dans XML], les applications doivent utiliser la valeur null comme paramètre namespaceURI dans les méthodes pour ne définir aucun espace de nommage.

errata : 2002-02-14
Paramètres
newAttr de type Attr
Le nœud Attr à ajouter à la liste d'attributs.
Valeur retournée

Attr

Si newAttr remplace un attribut existant avec les mêmes nom local et adresse URI d'espace de nommage, le nœud Attr remplacé est retourné, sinon la valeur null.

Exceptions

DOMException

WRONG_DOCUMENT_ERR : Soulevée si le paramètre newAttr a été créé à partir d'un document différent de celui qui a créé l'élément.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

INUSE_ATTRIBUTE_ERR : Soulevée si newAttr est déjà l'attribut d'un autre objet Element. L'utilisateur du DOM doit cloner explicitement les nœuds Attr pour leur réutilisation dans d'autres éléments.

NOT_SUPPORTED_ERR : Peut être soulevée si la mise en œuvre ne reconnaît pas la fonctionnalité "XML" et que le langage exposé au travers de l'interface Document ne reconnaît pas les espaces de nommage XML (tel que [HTML4]).

L'interface Text

L'interface Text hérite de CharacterData et représente le contenu textuel (appelé données textuelles→vf en XML) d'un nœud Element ou Attr. S'il n'y aucun balisage dans le contenu de l'élément, le texte se tient dans un seul objet mettant en œuvre l'interface Text qui est alors le seul enfant de l'élément. S'il y a un balisage, celui-ci est analysé dans les nœuds items d'information (éléments, commentaires, etc.) et Text qui forment la liste des enfants de l'élément.

Pour la première disponibilité d'un document via le DOM, il n'y a qu'un seul nœud Text pour chaque bloc de texte. Les utilisateurs peuvent créer des nœuds Text adjacents qui représentent le contenu d'un élément donné sans balisage intermédiaire, mais ils devraient tenir compte du fait qu'il n'existe aucun moyen de représenter les séparations entre ces nœuds en XML ou HTML, et ils ne persisteront donc pas (en général) entre des sessions d'édition du DOM. La méthode normalize() de l'interface Node fusionne ces objets Text adjacents en un seul nœud pour chaque bloc de texte.


Définition IDL
interface Text : CharacterData {
  Text               splitText(in unsigned long offset)
                                        raises(DOMException);
};

Méthodes
splitText
Partage ce nœud en deux à la position de décalage offset indiquée, en gardant ces deux nœuds dans l'arbre en tant que frères. Après le partage, ce nœud conservera tout le contenu juqu'à la position de décalage offset. Un nouveau nœud du même type, avec tout le contenu depuis la position de décalage offset et après, est retourné. Si le nœud original a un nœud parent, le nouveau nœud est inséré comme frère suivant du nœud original. Si la valeur du paramètre offset est égale à la longueur de ce nœud, le nouveau nœud ne contient aucune donnée.
Paramètres
offset of type unsigned long
La position de décalage, exprimée en unité de 16 bits, où intervient le partage ; elle commence à 0.
Valeur retournée

Text

Le nouveau nœud du même type que le nœud partagé.

Exceptions

DOMException

INDEX_SIZE_ERR : Soulevée si le décalage indiqué est négatif ou supérieur au nombre d'unités de 16 bits du paramètre data.

NO_MODIFICATION_ALLOWED_ERR : Soulevée si ce nœud est en lecture seule.

L'interface Comment

Cette interface hérite de CharacterData et représente le contenu d'un commentaire, c.à.d., tous les caractères entre la balise ouvrante <!-- et la balise fermante -->. Remarquer que c'est la définition d'un commentaire dans XML et, en pratique, dans HTML, quoique certains outils HTML puissent mettre en œuvre la structure de commentaire SGML complète.


Définition IDL
interface Comment : CharacterData {
};

1.3. Les interfaces étendues

Les interfaces définies ici forme un sous-ensemble de la spécification du DOM Core ; néanmoins, les objets qui exposent ces interfaces ne se rencontreront jamais dans une mise en œuvre DOM qui se rapporte seulement à HTML. Ainsi, les mises en œuvre DOM seulement HTML [DOM niveau 2 HTML] ne sont pas tenues de produire des objets pour mettre en œuvre ces interfaces.

Les interfaces dans cette section ne sont pas obligatoires. Une application DOM peut employer la méthode hasFeature(feature, version) de l'interface DOMImplementation, respectivement avec les valeurs de paramètre "XML" et "2.0", pour déterminer si ce module est géré ou non par la mise en œuvre. Pour la gestion complète de ce module, une mise en œuvre doit également gérer la fonctionnalité "Core", définie dans la section Les interfaces fondamentales. Cf. d'autres informations à propos de la conformité dans cette spécification.

L'interface CDATASection

On utilise les sections CDATA pour masquer des blocs de texte contenant des caractères qui seraient regardés comme du balisage sinon. Le seul délimiteur qui soit reconnu dans une section CDATA est la chaîne ]]> qui clôt la section CDATA en question. Les sections CDATA ne peuvent pas s'imbriquer. Leur but premier est d'inclure des documents tels que des fragments XML sans avoir besoin de masquer tous les délimiteurs.

L'attribut DOMString du nœud Text contient le texte qui apparaît dans la section CDATA. Remarquer que celui-ci est susceptible de contenir des caractères nécessitant un masquage en-dehors des sections CDATA et que, selon le codage de caractères ("charset") choisi pour la sérialisation, il peut être impossible d'écrire certains caractères dans une section CDATA.

L'interface CDATASection hérite de l'interface CharacterData au travers de l'interface Text. Les nœuds CDATASection adjacents ne sont pas fusionnés par la méthode normalize de l'interface Node.

Remarque : Puisqu'aucun balisage n'est reconnu dans un nœud CDATASection, on ne peut pas utiliser les appels numériques de caractère comme mécanisme de masquage pour une sérialisation. Il faudra donc prendre des mesures lors de la sérialisation d'un nœud CDATASection ayant un codage de caractères avec lequel certains des caractères qui y sont contenus ne pourront pas être représentés. Ne pas le faire conduirait à un code XML qui ne sera pas bien formé.
Une solution possible au cours du processus de sérialisation consisterait à clôre la section CDATA juste avant le caractère, à sortir le caractère en utilisant un appel de caractère ou d'entité puis à ouvrir une nouvelle section CDATA pour les caractères suivants du nœud de texte. Au moment de la rédaction, remarquer néanmoins que certaines bibliothèques de conversion de code ne retournent pas de condition d'erreur ou d'exception lorsqu'un caractère manque dans le codage, ce qui rend plus difficile la tâche de garantir la non-corruption des données dans une sérialisation.


Définition IDL
interface CDATASection : Text {
};

L'interface DocumentType

Chaque objet Document possède un attribut doctype dont la valeur est soit null, soit un objet DocumentType. L'interface DocumentType du DOM Core fournit une interface pour la liste des entités définies pour ce document et pas tellement plus, dans la mesure où les effets des espaces de nommage et des divers travaux sur les schémas XML sur la représentation des DTD ne sont pas encore clairement appréhendés au moment de la rédaction de cette spécification.

Le DOM niveau 2 ne gère pas l'édition des nœuds DocumentType. Les nœuds DocumentType sont en lecture seule.


Définition IDL
interface DocumentType : Node {
readonly attribute DOMString        name;
readonly attribute NamedNodeMap     entities;
readonly attribute NamedNodeMap     notations;
// Introduite dans DOM niveau 2 :
readonly attribute DOMString        publicId;
// Introduite dans DOM niveau 2 :
readonly attribute DOMString        systemId;
// Introduite dans DOM niveau 2 :
readonly attribute DOMString        internalSubset;
};

Attributs
entities de type NamedNodeMap, en lecture seule
Un objet NamedNodeMap contenant les entités générales, celles externes comme celles internes, déclarées dans le DTD. Les entités de paramètre ne s'y trouvent pas. Les doublons sont écartés. Par exemple :
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY truc "truc">
  <!ENTITY muche "muche">
  <!ENTITY muche "muche2">
  <!ENTITY % mache "mache">
]>
<ex/>
L'interface offre un accès à l'entité truc et la première déclaration de l'entité muche mais pas à la seconde déclaration de muche ni à celle de mache. Chaque nœud de cette carte met en œuvre également l'interface Entity.
Comme le DOM niveau 2 ne permet pas l'édition des entités, on ne peut donc pas modifier l'attribut entities.
internalSubset de type DOMString, en lecture seule, introduit dans DOM niveau 2
Le sous-ensemble interne sous forme d'une chaîne, ou la valeur null s'il n'y en a pas. Les crochets de délimitation ne sont pas compris.

Remarque : Le contenu réel retourné dépend de la quantité d'informations dont dispose la mise en œuvre. Elle peut varier en fonction de divers paramètres, y compris le processeur XML utilisé pour construire le document.

name de type DOMString, en lecture seule
Le nom de DTD, c.à.d., le nom qui suit immédiatement le mot-clé DOCTYPE.
notations de type NamedNodeMap, en lecture seule
Un objet NamedNodeMap contenant les notations déclarées dans le DTD. Les doublons sont écartés. Chaque nœud de cette carte met également en œuvre l'interface Notation.
Comme le DOM niveau 2 ne permet pas l'édition des notations, on ne peut donc en aucune façon modifier l'attribut notations.
publicId de type DOMString, en lecture seule, introduit dans DOM niveau 2
L'identificateur public du sous-ensemble externe.
systemId de type DOMString, en lecture seule, introduit dans DOM niveau 2
L'identificateur système du sous-ensemble externe. Il peut s'agir d'une adresse URI absolue ou non.
L'interface Notation

Cette interface représente une notation déclarée dans la définition de type de document (DTD). Une notation déclare, par le nom, le format d'une entité non-analysable (cf. la section 4.7→vf de la spécification XML 1.0 [XML]) ou bien sert à déclarer formellement des cibles d'instruction de traitement (cf. la section 2.6→vf de la spécification XML 1.0 [XML]). L'attribut nodeName, hérité de Node, prend le nom déclaré de la notation.

Comme le DOM niveau 1 ne permet pas l'édition des nœuds Notation, ils sont donc en lecture seule.

Un nœud Notation n'a aucun parent.


Définition IDL
interface Notation : Node {
  readonly attribute DOMString        publicId;
  readonly attribute DOMString        systemId;
};

Attributs
publicId de type DOMString, en lecture seule
L'identificateur public de cette notation. Si non indiqué, il a la valeur null.
systemId de type DOMString, en lecture seule
L'identificateur système de cette notation. Si non indiqué, il a la valeur null. Il peut s'agir d'une adresse URI absolue ou non.
L'interface Entity

Cette interface représente une entité, analysable ou non, dans un document XML. Remarquer qu'elle modélise l'entité en question et non la déclaration d'entité. La modélisation de la déclaration d'un objet Entity est laissée pour un niveau ultérieur de la spécification du DOM.

L'attribut nodeName, héritée de Node, contient le nom de l'entité.

Un processeur XML peut choisir de résoudre complètement les entités avant que le passage du modèle de structure au DOM ; auquel cas, il n'y aura pas de nœuds EntityReference dans l'arbre du document.

XML n'impose pas à un processeur XML non validant de lire et traiter les déclarations d'entités effectuées dans le sous-ensemble externe ou dans des entités de paramètre externe. Cela signifie que les entités analysables, déclarées dans le sous-ensemble externe, n'auront pas besoin d'être résolues par certaines classes d'application et que la valeur de remplacement le texte de remplacement de l'entité pourra être indisponible. Lorsque la valeur de remplacement le texte de remplacement→vf est disponible, la liste enfant du nœud Entity correspondant représente la structure de ce texte de remplacement cette valeur de remplacement. Sinon la liste enfant est vide.

Le DOM niveau 2 ne permet pas l'édition des nœuds Entity ; si un utilisateur veut apporter des changements au contenu d'un nœud Entity, chaque nœud EntityReference concerné doit être remplacé dans le modèle de structure par un clonage du contenu de Entity puis on doit effectuer à la place les changements voulus sur chacun des éléments clonés. Les nœuds Entity et tous leurs descendants sont en lecture seule.

Un nœud Entity n'a aucun parent.

Remarque : Si l'entité contient un préfixe d'espace de nommage non lié, l'attribut namespaceURI du nœud correspondant dans le sous-arbre du nœud Entity a la valeur null. Cela est également vrai pour les nœuds EntityReference qui se rapportent à cette entité lorsqu'ils sont créés par la méthode createEntityReference de l'interface Document. Le DOM niveau 2 n'offre aucun mécanisme de résolution des préfixes d'espace de nommage.


Définition IDL
interface Entity : Node {
  readonly attribute DOMString        publicId;
  readonly attribute DOMString        systemId;
  readonly attribute DOMString        notationName;
};

Attributs
notationName de type DOMString, en lecture seule
Pour les entités non analysables, le nom de la notation de l'entité. Pour les entités analysables, la valeur null.
publicId de type DOMString, en lecture seule
L'identificateur public associé à l'entité, si indiqué. Dans le cas contraire, la valeur null.
systemId de type DOMString, en lecture seule
L'identificateur système associé à l'entité, si indiqué. Dans le cas contraire, la valeur null. Il peut s'agir d'une adresse URI absolue ou non.
L'interface EntityReference

Les objets EntityReference peuvent s'insérer dans le modèle de structure quand un appel d'entité se trouve dans le document source ou quand l'utilisateur souhaite insérer un appel d'entité. Remarquer que les appels de caractères et d'entités prédéfinies sont censés être résolus par le processeur HTML, ou XML ; les caractères sont donc représentés par leur équivalent Unicode et non par un appel d'entité. En outre, le processeur XML peut résoudre en totalité les appels d'entités lors de la construction du modèle de structure, au lieu de fournir des objets EntityReference. S'il ne les fournit pas, alors, pour un nœud EntityReference donné, il se peut qu'il n'y ait aucun nœud Entity pour représenter l'entité appelée. Si un tel nœud Entity existe, alors le sous-arbre du nœud EntityReference est en général une copie du sous-arbre du nœud Entity. Par contre, cela ne se vérifie pas forcément lorsqu'une entité contient un préfixe d'espace de nommage non lié. Dans ce cas, puisque la résolution du préfixe d'espace de nommage dépend de la position de l'appel d'entité, les descendants du nœud EntityReference peuvent être liés à des adresses URI d'espaces de nommage différentes.

Comme pour les nœuds Entity, les nœuds EntityReference et tous leurs descendants sont en lecture seule.


Définition IDL
interface EntityReference : Node {
};

L'interface ProcessingInstruction

L'interface ProcessingInstruction représente une instruction de traitement utilisée en XML pour conserver une information spécifique pour le processeur dans le texte du document.


Définition IDL
interface ProcessingInstruction : Node {
  readonly attribute DOMString        target;
           attribute DOMString        data;
                                 // soulève une exception DOMException à l'initialisation

};

Attributs
data de type DOMString
Le contenu de cette instruction de traitement. C'est-à-dire, à partir du premier caractère non blanc après la cible jusqu'au caractère qui précède immédiatement le balisage ?>.
Exception à l'initialisation

DOMException

NO_MODIFICATION_ALLOWED_ERR : Soulevée quand le nœud est en lecture seule.

target de type DOMString, en lecture seule
La cible de cette instruction de traitement. XML la définit comme étant le premier atome qui suit la balise ouvrante de l'instruction de traitement.