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)

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 :

Document -- Element (un, au maximum), ProcessingInstruction, Comment, DocumentType (un, au maximum)
DocumentFragment -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
DocumentType -- aucun enfant
EntityReference -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
Element -- Element, Text, Comment, ProcessingInstruction, CDATASection, EntityReference
Attr -- Text, EntityReference
ProcessingInstruction -- aucun enfant
Comment -- aucun enfant
Text -- aucun enfant
CDATASection -- aucun enfant
Entity -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
Notation -- aucun enfant

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é.

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/".

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

DocumentFragment

Un nouveau DocumentFragment.

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].

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

ProcessingInstruction

Le nouvel objet ProcessingInstruction.

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

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

1. Le modèle objet de document Core

Table des matières

1.1. Vue d'ensemble des interfaces DOM Core

1.1.1. Le modèle de structure DOM

1.1.2. La gestion de la mémoire

1.1.3. Les conventions de nommage

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

1.1.5. Le type DOMString

1.1.6. Le type DOMTimeStamp

1.1.7. Les comparaison de chaînes dans le DOM

1.1.8. Les espaces de nommage XML

1.2. Les interfaces fondamentales

1.1.5. Le type `DOMString`

1.1.6. Le type `DOMTimeStamp`