REC-DOM-Level-1-19981001


1. Modèle Objet de Documents (Noyau) Niveau 1

Éditeurs
Mike Champion, ArborText (depuis le 20 novembre 1997)
Steve Byrne, JavaSoft (jusqu'au 19 novembre 1997)
Gavin Nicol, Inso EPS
Lauren Wood, SoftQuad, Inc.

Table des matières


1.1. Présentation générale des interfaces du noyau de DOM

Cette section définit un ensemble minimum d'objets et d'interfaces pour accéder et manipuler des objets documentaires. Les fonctionnalités spécifiées dans cette section (Les fonctionnalités du Noyau) devraient être suffisantes pour permettre aux développeurs de logiciels et les auteurs de scripts web d'accéder et de manipuler des contenus valides HTML et XML dans des produits conformes. L'API du Noyau de DOM permet aussi de remplir un objet Document en utilisant exclusivement des appels de l'API DOM ; la création du squelette du Document et la sauvegarde persistante est laissée à la charge du produit qui implémente l'API DOM.

1.1.1. Le modèle de structure de DOM

DOM présente les documents sous la forme d'une hiérarchie d'objets Node (noeuds) qui sont des objets implémentant eux-mêmes d'autres interfaces plus spécialisées. Certains types de noeuds peuvent avoir des noeuds enfants de types variés, et d'autres sont des feuilles (noeuds terminaux) pouvant ne rien avoir en dessous d'eux dans la structure du document. Les types de noeuds et ceux qu'ils peuvent avoir comme enfants sont respectivement donnés ci-après :

De plus, DOM spécifie l'interface NodeList (liste de noeuds) pour gérer des listes ordonnées de Nodes, comme par exemple les listes constituées des enfants d'un Node ou les éléments retournés par la méthode Element.getElementsByTagName, ainsi que l'interface NamedNodeMap (tableaux de noeuds nommés) qui permet de gérer des ensembles non ordonnés de noeuds référencés par leurs noms d'attributs tels que les attributs d'un Element. NodeList et NamedNodeMap sont dynamiques dans DOM, c'est à dire que les changements dans la structure du document sous-jacent sont réfléchis dans toutes les NodeList et les NamedNodeMap s'y rapportant . Par exemple, si un utilisateur de DOM obtient une NodeListcontenant les enfants d'un Element et qu'ensuite il ajoute de nouveaux enfants à cet élément (ou en retranche ou en modifie), ces changements sont automatiquement répercutés dans la NodeList sans que l'utilisateur n'ait aucune action particulière à faire. De la même manière, les changements faits sur un Node de l'arbre sont répercutés dans toutes les références faites à ce Node dans les NodeLists et les NamedNodeMaps.

1.1.2. Gestion de la mémoire

La plupart des APIs définies par cette spécification sont des interfaces plutôt que des classes. Cela signifie qu'une implémentation concrète n'a besoin de révéler que les méthodes ayant les noms définis et les traitements spécifiés, et non d'implémenter les classes qui découlent directement des interfaces. Cela permet aux Apis DOM d'être implémentées comme une fine surcouche au dessus d'anciennes applications ayant leurs propres structures de données, ou au dessus d'applications plus récentes mais ayant une hiérarchie de classes différente. Cela signifie aussi que les constructeurs ordinaires (au sens Java ou C++ du terme) ne peuvent pas être utilisés pour créer des objets DOM, puisque les objets sous-jacents à construire peuvent n'avoir qu'un faible rapport avec les interfaces DOM. La solution habituelle dans ce cas là d'un point de vue conception orientée objet est des définir des méthodes constructeur qui créent des instances d'objets dans lesquelles sont implémentées les différentes interfaces. Dans DOM niveau 1, les objets implémentant des interfaces "X" sont créés avec la méthode "createX()" de l'interface document; Cela parce que tous les objets DOM évoluent dans le contexte d'un document spécifique.

L'API DOM niveau 1 ne spécifie pas de moyen standard pour créer les objets DOMimplementation ou Document ; les implémentations effectives de DOM doivent fournir un moyen propriétaire pour rendre accessible ces interfaces DOM, et ensuite, tous les autres objets peuvent être construits à l'aide de la méthode Create de Document (ou par d'autres méthodes plus adaptées si besoin).

Les API du noyau de DOM sont conçues pour être compatibles avec une large gamme de langages, incluant à la fois les langages de commande pour tout un chacun et les langages plus performants plutôt utilisés par les programmeurs professionnels. Aussi, les Apis de DOM ont besoin de pouvoir fonctionner à travers une variété d'approches différentes concernant la gestion de la mémoire, depuis les langages qui ne dévoilent pas à l'utilisateur les problèmes de gestion de la mémoire, jusqu'à ceux (particulièrement C/C++) qui requièrent généralement du programmeur une gestion explicite des allocations mémoire, un suivi de son utilisation, et des ordres explicites de libération et réservation de place, en passant par ceux (notamment Java) qui fournissent des constructeurs explicites mais fournissent des ramasses miettes automatiques pour libérer la mémoire inutilisée. Pour garantir la cohérence de l'API DOM par rapport à ces différentes plates-formes, DOM ne traite absolument pas la question de la gestion de la mémoire, et laisse ces aspects aux choix de la réalisation. Aucune des correspondances explicites à des langages conçues par le groupe de travail sur DOM (pour ECMAScript et Java) ne nécessite d'établir une méthode de gestion de la mémoire, mais les correspondances de DOM pour d'autres langages (particulièrement C ou C++) nécessiteront probablement ce genre de support. Ces extensions seront de la responsabilité de ceux qui adapteront l'API DOM à un langage spécifique, et non de celle du groupe de travail sur DOM.

1.1.3. Conventions de nommage

Alors qu'il serait élégant d'avoir des noms de méthode et d'attribut courts, informatifs, cohérents intérieurement, et familiers aux utilisateurs d'APIs semblables, ils ne doivent cependant pas rentrer en conflits avec les noms des Apis existantes supportées par les implémentations de DOM. De plus, l'IDL de l'OMG et l'ECMAScript ont tous les deux des limitations significatives dans leur capacité à lever les ambiguïtés de noms entre différents espaces de noms rendant ainsi difficile la suppression des conflits avec des noms courts et familiers. Aussi, les noms DOM tendent à être longs et descriptifs afin d'être uniques dans tous les environnements.

Le groupe de travail a également essayé d'être cohérent en interne dans son utilisation des différents termes , même si certaines distinctions dans DOM peuvent être inutiles dans d'autres Apis Par exemple, nous utilisons des noms de méthode contenant le terme "remove" (retiré) quand la méthode change le modèle structurel, et le terme "delete" (détruit) quand la méthode supprime quelque chose à l'intérieur du modèle de structure. Quelque chose de détruit n'est pas retourné. Quelque chose de retiré peut, quand cela a un sens, être retourné.

1.1.4. Vues héritées versus vues aplaties de l'API

Les Apis du noyau DOM présentent deux ensembles quelques peu différents d'interfaces vers un documents XML/HTML ; l'un correspond à une approche "orientée objet" avec une hiérarchie d'héritage, et l'autre à une vue "simplifiée" autorisant toutes les manipulations permises par l'interface Node sans aucun recours aux transtypages (des langages Java ou d'autres apparentés à C) ou aux interfaces de requête des environnements COM. Ces traitements sont très coûteux en Java et COM, et DOM doit pouvoir être utilisé dans des environnements critiques en terme de performances, ainsi nous autorisons des fonctionnalités significatives n'utilisant que l'interface Node. Comme beaucoup d'autres utilisateurs peuvent trouver l'approche hiérarchique de l'héritage plus facile à comprendre pour DOM que l'approche "tout n'est que Node", nous supportons aussi la totalité des interfaces de haut niveau pour ceux qui préfèrent une API plus orientée objet.

En pratique, cela signifie qu'il y a un certain niveau de redondance dans l'API. Le groupe de travail considère que l'approche hiérarchique de l'héritage est la vue principale de l'API, et que l'ensemble complet des fonctions sur un Node est un "extra" que les utilisateurs peuvent employer, mais qui n'élimine pas le besoin d'avoir des méthodes pour d'autres interfaces quand une approche orientée objet les imposent (naturellement, lorsque un attribut ou une méthode ayant résulté de l'analyse orientée objet est identique à l'un de ceux de l'interface Node, on n'en spécifie pas un nouveau totalement redondant). Ainsi, même si l'attribut générique nodeName existe dans l'interface noeud, il existe néanmoins un attribut tagName dans l'interface élément; Ces deux attributs doivent contenir la même valeur, mais le groupe de travail considère qu'il est valable de supporter les deux, étant donné les différents constituants auxquels l'API DOM doit satisfaire.

1.1.5. Le type DOMString

Pour garantir l'interopérabilité, DOM spécifie le type DOMString comme suit :

Note : en août 1998 la spécification de l'IDL de l'OMG incluait un type wstring. Toutefois, cette définition ne respectait pas les critères d'interopérabilité de l'API DOM puisqu'elle reposait sur une négociation d'encodage pour décider de la taille d'un caractère.

1.1.6. La sensibilité à la casse dans DOM

Plusieurs interfaces de DOM impliquent des recherches de chaînes de caractères. Les processeurs HTML normalisent, en général, les noms des éléments en majuscule (plus rarement en minuscule) alors que XML est clairement sensible à la casse. Pour les besoins de DOM, la correspondance d'une chaîne se fait sur la base d'une comparaison code de caractère par code de caractère dans un type DOMString codé sur 16 bits. DOM garantit ainsi que toute normalisation est assurée par processeur, avant que toute structure DOM ne soit construite.

Cela accentue exactement ce pour quoi la normalisation a été faite. Le groupe de travail I18N du W3C est actuellement en train de définir exactement quelles normalisations sont nécessaires aux applications implémentant DOM.

1.2. Interfaces fondamentales

Les interfaces de cette section sont considérées comme fondamentales, et doivent être complètement implémentées par toutes les implantations de DOM conformes, y compris les implémentations de DOM pour HTML.

Exception DOMException

Les opérations DOM ne provoquent des exceptions qu'en cas de circonstances "exceptionnelles". Par exemple, quand une opération est impossible à réaliser (pour des raisons logiques, parce que des données sont perdues, ou parce que l'implémentation DOM est devenue instable). En général, les méthodes DOM retournent des codes d'erreur spécifiques pour les cas ordinaires de traitement, comme par exemple les erreurs de dépassement de dimensions dans l'utilisation de NodeList.

Les réalisations DOM peuvent déclencher d'autres exceptions dans d'autres circonstances. Par exemple, des implémentations peuvent déclencher des exceptions qui leurs sont spécifiques si un argument null est utilisé.

Certains langages et systèmes objet ne supportent pas le concept des exceptions. Pour de tels systèmes, les conditions d'erreur peuvent être indiquées en utilisant les mécanismes de report d'erreur natifs. Pour certaines implémentations, par exemple, les méthodes peuvent retourner des codes d'erreur similaires à ceux listés dans les descriptions des méthodes correspondantes.
Définition IDL

exception DOMException {
  unsigned short  code;
};
// Code d'exception
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;
            
Définition de ExceptionCode

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

INDEX_SIZE_ERR

Si l'indice ou la taille est négatif, ou plus grand que la valeur autorisée

DOMSTRING_SIZE_ERR

Si la fourchette de texte spécifiée ne rentre pas dans une DOMString

HIERARCHY_REQUEST_ERR

Si un noeud est inséré à un endroit auquel il n'appartient pas

WRONG_DOCUMENT_ERR

Si un noeud est utilisé dans un document autre que celui qui l'a créé (et qui, par conséquent, ne peut le supporter)

INVALID_CHARACTER_ERR

Si un caractère invalide est spécifié, comme dans un nom par exemple.

NO_DATA_ALLOWED_ERR

Si une donnée est spécifiée pour un noeud qui ne supporte pas de donnée

NO_MODIFICATION_ALLOWED_ERR

Si on tente de modifier un objet qui ne peut pas être modifié

NOT_FOUND_ERR

Si on tente de référencer un noeud dans un contexte où il n'existe pas

NOT_SUPPORTED_ERR

Si l'implémentation ne supporte pas le type de l'objet demandé

INUSE_ATTRIBUTE_ERR

Si une tentative est faite pour ajouter un attribut qui est déjà utilisé par ailleurs

Interface DOMImplementation

L'interface DOMImplementation fournit un certain nombre de méthodes pour réaliser des traitements indépendants de toute instance particulière du modèle objet de documents.

DOM niveau 1 ne spécifie pas la manière de créer des instances de documents, et donc la création d'un document est une opération spécifique à une implémentation. Les futurs niveaux de la spécification DOM devraient fournir les méthodes pour créer directement des documents.

Définition IDL
interface DOMImplementation {
  boolean     hasFeature(in DOMString feature, in DOMString version);
};
            
Méthodes
hasFeature
Teste si l'implémentation de DOM supporte une caractéristique spécifique.
Paramètres
feature

Le nom de paquetage de la caractéristique à tester. Dans DOM niveau 1, les valeurs autorisées sont "HTML" et "XML" (non sensible à la casse).

version

C'est le numéro de version du nom de paquetage à tester. Dans DOM niveau 1, c'est la chaîne de caractères "1.0". Si la version n'est pas spécifiée, supporter n'importe quelle version de la caractéristique fera que la méthode retournera true.

Valeur retournée
true si la caractéristique est implantée dans la version spécifiée, false sinon.

Cette méthode ne provoque aucune exceptions.
Interface DocumentFragment

DocumentFragment est un objet document qui pourrait être qualifié "d'allégé" ou encore de "minimum". Il est très courant de vouloir extraire un morceau de l'arbre d'un document ou de vouloir créer un nouveau fragment de document. Imaginez l'implémentation d'une commande utilisateur tel que la fonction "couper" ou la réorganisation d'un document par déplacements de fragments : il est souhaitable d'avoir un objet auquel on puisse rattacher les fragments et il est tout à fait naturel d'utiliser un noeud pour cela. Même s'il est vrai qu'un objet de type document pourrait assurer ce rôle, ce type d'objet est potentiellement lourd, suivant l'implémentation sous-jacente. Ce qui est vraiment utile pour les fonctions souhaitées, c'est de pouvoir disposer d'un objet très léger. DocumentFragment est justement ce genre d'objet.

De plus, certaines fonctions -- comme l'insertion de noeuds en tant qu'enfants d'un autre Node -- peuvent avoir des objets DocumentFragment comme arguments ; cela entraîne le déplacement de tous les noeuds enfants de l'objet DocumentFragment vers la liste des enfants de ce noeud

L'objet DocumentFragment peut avoir zéro ou plusieurs noeuds enfants représentant les sommets de n'importe quels sous-arbres définissant la structure du document. L'ensemble de noeuds composant un DocumentFragment n'a pas besoin d'être un document XML bien formé (bien qu'il ait cependant besoin d'être conforme aux règles imposées aux entités valides XML bien formées, pouvant avoir plusieurs noeuds au dessus). Par exemple, un DocumentFragment pourrait avoir uniquement un enfant et celui-là pourrait être un noeud Text. Un tel modèle de structure ne représente ni un document HTML ni un document XML bien formé.

Quand un DocumentFragment est inséré dans un Document (ou évidemment tout autre Node pouvant avoir des enfants), les noeuds enfants de DocumentFragmentet non le DocumentFragment lui même sont insérés dans l'objet Node. Cela rend l'objet DocumentFragment très utile quand l'utilisateur souhaite créer des noeuds frères ; DocumentFragment agit alors comme le parent de ces noeuds de manière à ce que l'utilisateur puisse utiliser les méthodes standard de l'interface Node, comme par exemple les méthodes insertBefore() et appendChild().

Définition IDL
interface DocumentFragment : Node {
};
            
Interface Document

L'interface Document représente tout le document HTML ou XML. Conceptuellement, il s'agit de la racine de l'arbre du document, et fournit l'accès principal aux données du document.

Puisque les éléments, les noeuds textuels, les commentaires, les instructions de traitement, etc... ne peuvent exister en dehors du contexte Document, l'interface Document contient également les méthodes nécessaires pour créer ces objets. Les objets Node créés ont un attribut ownerDocument qui les associe 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)
                                          provoque (DOMException);
  DocumentFragment          createDocumentFragment();
  Text                      createTextNode(in DOMString data);
  Comment                   createComment(in DOMString data);
  CDATASection              createCDATASection(in DOMString data)
                                          provoque (DOMException);
  ProcessingInstruction     createProcessingInstruction(in DOMString target, 
                                                        in DOMString data)
                                           provoque (DOMException);
  Attr                      createAttribute(in DOMString Name)
                                           provoque (DOMException);
  entityReference           createEntityReference(in DOMString name)
                                           provoque (DOMException);
  NodeList                  getElementsByTagName(in DOMString tagName);
};
            
Attributs
doctype
La Déclaration de Type de Document (DTD) (voir DocumentType) associée à ce document. Pour les documents HTML ainsi que pour les documents XML sans déclaration de type de document, la valeur null est retournée. DOM niveau 1 ne supporte pas l'édition de la Déclaration de Type de Document, par conséquent, la valeur de doctype ne peut en aucun cas être modifié.
implementation
L'objet DOMImplementation qui gère le document. Une application DOM peut utiliser des objets de différentes implémentations.
documentElement
C'est un attribut pratique permettant un accès direct au noeud enfant qui n'est rien d'autre que le noeud racine du document. Pour les documents HTML, il s'agit de l'élément dont le nom (tagName) est "HTML".
Méthodes
createElement
Crée un élément du type spécifié. Notez que l'instance retournée implémente l'interface Element, donc les attributs peuvent être spécifiés directement sur l'objet retourné.
Paramètres
tagName

Le nom du type de l'élément à instancier. Pour XML, il est sensible à la casse. Pour HTML, le paramètre tagName peut être fourni indifféremment de la casse, mais il doit être mis en correspondance avec la forme canonique majuscule par l'implémentation de DOM.

Valeur retournée
Un nouvel objet Element.
Exceptions
DOMException

INVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère invalide.


createDocumentFragment
Crée un objet DocumentFragment vide.
Valeur retournée
Un nouveau DocumentFragment.

Cette méthode n'a pas de paramètre.
Cette méthode ne provoque aucune exception.
createTextNode
Crée un noeud Text contenant la chaîne de caractères spécifiée.
Paramètres
data

Les données du noeud

Valeur retournée
Le nouvel objet Text.

Cette méthode ne provoque aucune exception.
createComment
Crée un noeud Comment contenant la chaîne de caractères spécifiée.
Paramètres
data

Les données du noeud

Valeur retournée
Le nouvel objet Comment.

Cette méthode ne provoque aucune exception.
createCDATASection
Crée un noeud CDATASection dont la valeur est la chaîne de caractères spécifiée.
Paramètres
data

Les données formant le contenu de la section CDATASection.

Valeur retournée
Le nouvel objet CDATASection.
Exceptions
DOMException

NOT_SUPPORTED_ERR : provoquée si le document est un document HTML.


createProcessingInstruction
Crée un noeud ProcessingInstruction ayant le nom et les chaînes de caractères de données spécifiés.
Paramètres
target

La partie cible de l'instruction de traitement.

data

Les données du noeud

Valeur retournée
Le nouvel objet ProcessingInstruction.
Exceptions
DOMException

INVALID_CHARACTER_ERR : provoquée si un caractère non valide est spécifié.

NOT_SUPPORTED_ERR : provoquée si le document est un document HTML.


createAttribut
Crée un objet Attr d'un nom donné. Notez que l'instance de l'objet Attr peut ensuite être rattachée à un Element en utilisant la méthode setAttribute.
Paramètres
name

Le nom de l'attribut.

Valeur retournée
Un nouvel objet Attr.
Exceptions
DOMException

INVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère non valide.


createEntityReference
Crée un objet EntityReference.
Paramètres
name

Le nom de l'entité à référencer.

Valeur retournée
Le nouvel objet EntityReference.
Exceptions
DOMException

INVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère non valide.

NOT_SUPPORTED_ERR : provoquée si le document est un document HTML.


getElementsByTagName
Retourne un objet NodeList (une liste de noeuds) de tous les objets Elements ayant un nom de balise donné, laquelle est ordonnée selon l'ordre de lecture prédéfini de l'arbre du Document.
Paramètres
tagName

Le nom de l'élément à trouver. La valeur spéciale "*" signifie qu'il faut chercher tous les éléments.

Valeur retournée
Un nouvel objet NodeList contenant tous les objets Elements correspondant.

Cette méthode ne provoque aucune exception.
Interface Node

L'interface Node est le type de donnée principal de tout le Modèle Objet de Document. Il représente un noeud unique de l'arbre du document. Bien que que tous les objets implémentant l'interface Node fournissent des méthodes pour traiter leurs enfants, tous les objets implémentant l'interface Node n'ont pas forcement d'enfants. Par exemple, les noeuds Text ne peuvent pas avoir d'enfant, et en rajouter doit déclencher une exception DOMException.

Les attributs nodeName, nodeValue et attributes sont des mécanismes permettant d'obtenir des informations sur le noeud sans avoir à aller chercher l'interface dérivée spécifique. Dans le cas où il n'y a pas de correspondance évidente de ces attributs pour un NodeType particulier (par exemple : la valeur de l'attribut nodeValue d'un élément ou celle de l'attribut attributes d'un commentaire), leur valeur est null. Notez que des interfaces spécialisées peuvent permettre d'avoir des mécanismes additionnels ou plus pratiques pour initialiser et lire l'information pertinente.

Définition IDL
interface Node {
  // Type de noeud
  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;
                                  // provoque une exception(DOMException) à l'initialisation
                                  // provoque une exception(DOMException) à l'utilisation
  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;
  readonly attribute  Document             ownerDocument;
  Node                      insertBefore(in Node newChild, 
                                         in Node refChild)
                                         provoque(DOMException);
  Node                      replaceChild(in Node newChild, 
                                         in Node oldChild)
                                         provoque(DOMException);
  Node                      removeChild(in Node oldChild)
                                        provoque(DOMException);
  Node                      appendChild(in Node newChild)
                                        provoque(DOMException);
  boolean                   hasChildNodes();
  Node                      cloneNode(in boolean deep);
};
            
Groupe de Définition de NodeType

Un entier indique le type de noeud dont il s'agit.

Constantes définies
ELEMENT_NODE

Le noeud est un Element.

ATTRIBUTE_NODE

Le noeud est un Attr.

TEXT_NODE

Le noeud est un Text.

CDATA_SECTION_NODE

Le noeud est une CDATASection.

ENTITY_REFERENCE_NODE

Le noeud est une EntityReference.

ENTITY_NODE

Le noeud est une Entity.

PROCESSING_INSTRUCTION_NODE

Le noeud est une ProcessingInstruction

COMMENT_NODE

Le noeud est un Comment.

DOCUMENT_NODE

Le noeud est un Document.

DOCUMENT_TYPE_NODE

Le noeud est un DocumentType.

DOCUMENT_FRAGMENT_NODE

Le noeud est un DocumentFragment.

NOTATION_NODE

Le noeud est une Notation.

Les attributs nodeName, nodeValue, et attributes ont des valeurs qui varient en fonction des types de noeuds comme suit :

Type_du_noeud nodeName nodeValue attributs
Element tagName (le nom de l'élément) null NameNodeMap
Attr Le nom de l'attribut La valeur de l'attribut null
Text #text Le contenu du noeud textuel null
CDATASection #cdata-section Le contenu de la section CDATA null
EntityReference Le nom de l'entité référencée null null
Entity Le nom de l'entité null null
ProcessingInstruction La cible tout le contenu excepté la cible null
Comment #comment Le contenu du commentaire null
Document #document null null
DocumentType Le nom du type de document null null
DocumentFragment #document-fragment null null
Notation Le nom de la notation null null
Attributs
nodeName
Le nom de ce noeud, qui dépend de son type; voir la table ci-dessus.
nodeValue
La valeur de ce noeud, qui dépend de son type; voir la table ci-dessus.
Exceptions à l'initialisation
DOMException

NO_MODIFICATION_ALLOWED_ERR : provoquée lorsque le noeud est en lecture seule.

Exceptions à l'utilisation
DOMException

DOMSTRING_SIZE_ERR : provoquée au cas où le nombre de caractères retourné dépasse la capacité de la variable DOMString telle qu'elle est définie par l'implémentation.

nodeType
Un code représentant le type d'objet sous-jacent, tel que défini ci-dessus.
parentNode
Le parent de ce noeud Tous les noeuds, excepté Document, DocumentFragment, et Attr peuvent avoir un parent. Toutefois, si un noeud vient juste d'être créé et n'est pas encore inséré dans l'arbre, ou si il a été retiré de l'arbre, cette valeur est null.
childNodes
La liste de noeuds (NodeList) constituée des enfants du noeud Si le noeud n'a pas d'enfant, la liste ne contient aucun noeud Le contenu de la liste NodeList retournée est "vivant" dans le sens que, par exemple, les changements affectant les enfants créés à partir de l'objet noeud sont immédiatement répercutés sur les noeuds retournés par les méthodes d'accès de la liste NodeList ; il ne s'agit pas d'une photographie instantanée statique du contenu du noeud Cela est vrai pour toute liste NodeList, y compris celles retournées par la méthode getElementsByTagName.
firstChild
Le premier enfant de ce noeud Si un tel noeud n'existe pas, la valeur null est retournée.
lastChild
Le dernier enfant de ce noeud Si un tel noeud n'existe pas, la valeur null est retournée.
previousSibling
Le noeud qui précède immédiatement le noeud courant. Si un tel noeud n'existe pas, la valeur null est retournée.
nextSibling
Le noeud qui suit immédiatement le noeud courant. Si un tel noeud n'existe pas, la valeur null est retournée.
attributes
Un NameNodeMap contenant les attributs de ce noeud (si c'est un Element) ou null sinon.
ownerDocument
L'objet Document associé à ce noeud Cela est aussi l'objet Document utilisé pour créer de nouveaux noeuds Quand ce noeud est un Document la valeur vaut null.
Méthodes
insertBefore
Insère le noeud newChild avant le noeud enfant refChild (si ce dernier existe). Si refChild est null, alors newChild est inséré à la fin de la liste des enfants.

Si newChild est un objet de type DocumentFragment, tout ses enfants sont insérés, dans le même ordre, avant refChild. Si le newChild est déjà dans l'arbre, il est d'abord retiré.

Paramètres
newChild

Le noeud à insérer.

refChild

Le noeud de référence, c'est à dire, le noeud avant lequel le nouveau noeud doit être inséré.

Valeur retournée
Le noeud inséré.
Exceptions
DOMException

HIERARCHY_REQUEST_ERR : provoquée si le noeud courant est d'un type n'admettant pas un noeud enfant du type de newChild, ou si le noeud à insérer est l'un des ancêtres du noeud courant.

WRONG_DOCUMENT_ERR : provoquée si newChild a été créé dans un document autre que celui dans lequel le noeud courant a été créé.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud courant est en lecture seule.

NOT_FOUND_ERR : provoquée si refChild n'est pas un enfant du noeud courant.


replaceChild
Remplace le noeud enfant oldChild par newChild dans la liste des enfants, et retourne le noeud oldChild. Si le newChild est déjà dans l'arbre, il en est d'abord retiré.
Paramètres
newChild

Le nouveau noeud à mettre dans la liste des enfants.

oldChild

Le noeud à remplacer dans la liste.

Valeur retournée
Le noeud remplacé.
Exceptions
DOMException
HIERARCHY_REQUEST_ERR : provoquée si le noeud courant ne peut avoir un noeud enfant du type de newChild, ou si le noeud à insérer est l'un des ancêtres du noeud courant.

WRONG_DOCUMENT_ERR : provoquée si le noeud newChild a été créé dans un document autre que celui dans lequel le noeud courant a été créé.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud courant est en lecture seule.

NOT_FOUND_ERR : provoquée si oldChild n'est pas un enfant du noeud courant.

removeChild
Retire le noeud enfant oldChild de la liste des enfants, et le retourne.
Paramètres
oldChild

Le noeud à retirer.

Valeur retournée
Le noeud retiré.
Exceptions
DOMException
NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud courant est en lecture seule.

NOT_FOUND_ERR : provoquée si oldChild n'est pas un enfant du noeud courant.

appendChild
Ajoute le noeud newChild à la fin de la liste des noeuds enfants du noeud courant. Si newChild est déjà dans l'arbre, il est d'abord retiré.
Paramètres
newChild

Le noeud à rajouter.

Si newChild est un objet de type DocumentFragment, la totalité du contenu du fragment est déplacé vers la liste des enfants du noeud courant.

Valeur retournée
Le noeud rajouté.
Exceptions
DOMException
HIERARCHY_REQUEST_ERR : provoquée si le noeud courant ne peut avoir un noeud enfant du type de newChild, ou si le noeud à insérer est l'un des ancêtres du noeud courant.

WRONG_DOCUMENT_ERR : provoquée si le noeud newChild a été créé dans un document autre que celui dans lequel le noeud courant a été créé.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud courant est en lecture seule.

hasChildNodes
C'est une méthode pratique qui permet de savoir si un noeud a des enfants.
Valeur retournée
true si le noeud a un enfant, false sinon.

Cette méthode n'a pas de paramètre.
Cette méthode ne provoque aucune exception.
cloneNode
Retourne un clone de ce noeud, c'est à dire, qu'elle est utilisée comme constructeur générique pour copier des noeuds Le noeud cloné n'a pas de parent (c'est à dire que si on lui applique la méthode parentNode la valeur retournée est null.).

Le clonage d'un objet Element copie tous les attributs et leur valeur, y compris ceux générés par le processeur XML et qui correspondent aux attributs ayant des valeurs par défaut. Mais cette méthode ne copie aucun texte contenu dans le noeud à moins qu'il ne s'agisse d'un clonage profond, puisque le texte est contenu dans un noeud enfant de type Text. Cloner tout autre type de noeud ne fait que retourner une copie du noeud courant.

.
Paramètres
deep

Si true, clone récursivement le sous-arbre du noeud spécifié;

Si false, ne clone que le noeud lui-même (et ses attributs, si c'est un noeud de type Element).

Valeur retournée
Le noeud dupliqué.

Cette méthode ne provoque aucune exception.
Interface NodeList

L'interface NodeList fournit une abstraction d'une collection ordonnée de noeuds, sans définition ou contrainte sur l'implémentation de cette collection.

Les items de la NodeListsont accessibles via un indice intégral, commençant à 0.

Définition IDL
interface NodeList{
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};
            
Méthodes
item
Retourne l'item de la collection se trouvant à la position spécifiée par le paramètre index. Si index est supérieure ou égale au nombre de noeuds de la collection, la méthode retourne la valeur null.
Paramètres
index

La position dans la collection.

Valeur retournée
Le noeud se trouvant à la position index dans la NodeList, ou null si la valeur du paramètre index n'est pas valide.

Cette méthode ne provoque aucune exception.
Attributs
length
Le nombre de noeuds dans la liste. Le domaine de validité du paramètre index va de 0 à length-1 inclus.
Interface NameNodeMap

Les objets implémentant l'interface NameNodeMap sont utilisés pour représenter des collections de noeuds directement adressables par un nom. Notez que NameNodeMap n'hérite pas de l'objet NodeList ; en effet NameNodeMap n'impose pas un ordonnancement particulier des noeuds Les objets contenus dans un autre objet implémentant NameNodeMap peuvent aussi être adressés par un numéro d'ordre, mais cela n'est qu'un moyen pratique permettant une énumération des contenus d'un objet de type NameNodeMap, et n'implique donc pas qu'il s'agisse d'un ordre particulier des noeuds qui serait imposé par DOM.

Définition IDL
interface NameNodeMap {
  Node                      getNamedItem(in DOMString name);
  Node                      setNamedItem(in noeud arg)
                                         provoque(DOMException);
  Node                      removeNamedItem(in DOMString name)
                                            provoque (DOMException);
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};
            
Méthodes
getNamedItem
Permet d'obtenir un noeud à partir de son nom.
Paramètres
name

Nom du noeud à obtenir.

Valeur retournée
Le Node (de n'importe quel type) ayant le nom spécifié en paramètre, ou la valeur null si le nom spécifié ne s'applique à aucun des noeuds présent dans la table.

Cette méthode ne provoque aucune exception.
setNamedItem
Ajoute un noeud en utilisant son attribut nodeName.

Comme l'attribut nodeName est utilisé pour connaître le nom sous lequel le noeud doit être stocké, plusieurs noeuds d'un même type (ceux qui ont une valeur textuelle "spéciale") ne peuvent pas être stockés puisque leurs noms rentreraient alors en collision. Cela parait être préférable à une situation où les noeuds pourraient recevoir des alias.

Paramètres
arg

Un noeud à stocker dans une table de noeuds nommés. Le noeud sera plus tard accessible en utilisant la valeur de son attribut nodeName. Si un noeud avec ce nom est déjà présent dans la table, il est remplacé par le nouveau.

Valeur retournée
Si le nouveau Node remplace un noeud existant ayant le même nom, le Node remplacé est retourné , sinon la valeur retournée est null.
Exceptions
DOMException

WRONG_DOCUMENT_ERR : provoquée si l'argument arg a été créé dans un autre document que celui qui servit à créer le NameNodeMap.

NO_MODIFICATION_ALLOWED_ERR : provoquée si NameNodeMap est en lecture seule.

INUSE_ATTRIBUTE_ERR : provoquée si l'argument arg est de type Attr déjà utilisé sur un autre objet Element. L'utilisateur de DOM doit explicitement cloner les noeuds Attr avant de pouvoir les réutiliser dans d'autres éléments.


removeNamedItem
Retire un noeud spécifié par son nom. Si le noeud retiré est de type Attr ayant une valeur par défaut, il est immédiatement remplacé.
Paramètres
name

Le nom du noeud à retirer.

Valeur retournée
Le noeud retiré de la table des noeuds nommés ou la valeur null si aucun noeud de ce nom n'existe dans cette table.
Exceptions
DOMException

NOT_FOUND_ERR : provoquée si il n'y a pas dans la table de noeud ayant le nom name.


item
Retourne l'élément à la position index du NameNodeMap. Si la valeur de index est supérieure ou égale au nombre de noeuds de la table, la valeur retournée est null.
Paramètres
index

La position dans la table.

Valeur retournée
Le noeud de la table NameNodeMap se trouvant à la position spécifiée par index , ou null si la valeur de index n'est pas valide.

Cette méthode ne provoque aucune exception.
Attributs
length
Le nombre de noeuds présents dans la table. La valeur de l'indice peut varier de 0 à length-1 inclus.
Interface CharacterData

L'interface CharacterData est une extension de l'interface Node qui se caractérise par un ensemble d'attributs et de méthodes supplémentaires permettant d'adresser des données caractères dans le Modèle Objet de Documents. Pour des raisons de clarté, cet ensemble est défini ici plutôt que dans chaque objet qui utilise ces attributs et méthodes. Aucun objet DOM ne peut directement correspondre au type CharacterData, bien que l'objet Text et d'autres en héritent leur interface. Toutes les valeurs de type offsets de cet interface commencent à 0.

Définition IDL
interface CharacterData : Node {
  attribut  DOMString            data;
                                 // provoque (DOMException)  à l'initialisation
                                 // provoque (DOMException) à l'utilisation
  readonly attribute  unsigned long        length;
  DOMString        substringData(in unsigned long offset, 
                                 in unsigned long count)
                                 provoque (DOMException);
  void              appendData(in DOMString arg)
                               provoque (DOMException);
  void              insertData(in unsigned long offset, 
                               in DOMString arg)
                               provoque (DOMException);
  void              deleteData(in unsigned long offset, 
                               in unsigned long count)
                               provoque (DOMException);
  void              replaceData(in unsigned long offset, 
                                in unsigned long count, 
                                in DOMString arg)
                                provoque (DOMException);
};
            
Attributs
data
Les données caractères du noeud qui implémente cet interface. L'implémentation de DOM peut ne pas fixer de limite arbitraire à la quantité de données pouvant être stockée dans un noeud de type CharacterData. Toutefois, les limites des réalisations peuvent signifier que la totalité des données d'un noeud peuvent ne pas tenir dans un seul objet de type DOMString. Dans ce cas, l'utilisateur peut utiliser la méthode substringData pour récupérer les données par morceaux de tailles appropriées.
Exceptions à l'initialisation
DOMException

NO_MODIFICATION_ALLOWED_ERR : provoquée quand le noeud est en lecture seule .

Exceptions à l'utilisation
DOMException

DOMSTRING_SIZE_ERR : provoquée si la taille de la donnée retournée dépasse la capacité du type DOMString de l'implémentation.

length
Le nombre de caractères disponibles au travers de l'attribut data et de la méthode substringData ci-dessous. Cet attribut peut prendre la valeur zéro, ce qui veut dire qu'un noeud CharacterData peut être vide.
Méthodes
substringData
Extrait un champ de caractères à partir du noeud
Paramètres
offset

décalage de départ de la sous-chaîne à extraire.

count

Le nombre de caractères à extraire.

Valeur retournée
La sous-chaîne spécifiée. Si la somme du décalage (offset) et de la longueur (count) dépasse la valeur spécifiée pour l'attribut length, alors, tous les caractères de la chaîne à partir du décalage jusqu'à la fin sont retournés.
Exceptions
DOMException

INDEX_SIZE_ERR : provoquée si le décalage spécifié est négatif ou plus grand que le nombre de caractères de l'attribut data, ou si la valeur spécifiée pour le paramètre count est négatif.

DOMSTRING_SIZE_ERR : provoquée si la portion de texte spécifiée ne tient pas dans une variable DOMString.


appendData
Ajoute la chaîne de caractère à la fin des données caractères du noeud En cas de succès, l'attribut data permet d'avoir accès à la concaténation des données data et de la variable DOMString spécifiée.
Paramètres
arg

La DOMString à ajouter.

Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
insertData
Insère une chaîne de caractère à l'endroit spécifié par un décalage de caractère.
Paramètres
offset

Le décalage de caractère spécifiant l'endroit où il faut insérer la chaîne.

arg

La DOMString à insérer.

Exceptions
DOMException

INDEX_SIZE_ERR : provoquée si le décalage spécifié est négatif ou plus grand que le nombre de caractères présents dans l'attribut data.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
deleteData
Retire un champ de caractères du noeud En cas de succès, les attributs data et length sont mis à jour en fonction de la modification effectuée.
Paramètres
offset

Le décalage à partir duquel il faut retirer des caractères.

count

Le nombre de caractères à supprimer. Si la somme de offset et count dépasse la valeur de l'attribut length alors tous les caractères depuis la position offset jusqu'à la fin sont supprimés.

Exceptions
DOMException

INDEX_SIZE_ERR : provoquée si le décalage spécifié est négatif ou plus grand que le nombre de caractère de l'attribut data, ou si la valeur de count spécifiée est négative.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
replaceData
Remplace les caractères à partir du décalage spécifié par une nouvelle chaîne de caractère.
Paramètres
offset

Le décalage à partir d'où il faut commencer le remplacement.

count

Le nombre de caractères à remplacer. Si la somme de offset et count dépasse la valeur de l'attribut length, alors tous les caractères depuis la position offset jusqu'à la fin sont remplacés (c'est à dire que l'effet est le même que si on exécutait successivement les méthodes remove et append).

arg

La variable DOMString qui contient la chaîne de remplacement.

Exceptions
DOMException

INDEX_SIZE_ERR : provoquée si le décalage spécifié est négatif , ou si le paramètre count spécifié est négatif.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
Interface Attr

L'interface Attr représente un attribut d'un objet de type Element. Typiquement, les valeurs autorisées de l'attribut sont spécifiées dans une DTD (Définition de Type de Document).

Les objets Attr héritent de l'interface noeud, mais comme ils ne sont pas vraiment des noeuds enfants de l'élément qu'ils décrivent, le Modèle Objet de Document DOM ne les considère pas comme partie intégrante de l'arbre. Ainsi, les attributs parentNode, previousSibling, et nextSibling de noeud ont la valeur null pour les objets Attr. Le Modèle Objet de Documents considère les attributs comme des propriétés des éléments plutôt que comme des objets ayant une identité distincte des éléments auxquels ils sont associés. Cela devrait rendre plus efficace d'implémenter de telles caractéristiques comme attributs par défaut associés à des éléments d'un type donné. De plus, les noeuds Attr ne peuvent pas être des enfants immédiats d'un DocumentFragment. Toutefois, ils peuvent être associés à des noeuds de type Element contenus dans un DocumentFragment. Finalement, les utilisateurs et les développeurs d'applications DOM doivent faire attention à ce que les noeuds Attr aient quelque chose en commun avec les autres objets héritant de l'interface Node, même si ils en sont tout à fait distincts.

La valeur effective de l'attribut est déterminée comme suit : si une valeur a été explicitement assignée à cet attribut, cette valeur est la valeur effective de l'attribut; sinon, si il existe une déclaration pour cet attribut et que celle-là lui définisse une valeur par défaut, alors cette valeur par défaut est la valeur effective de l'attribut; sinon, l'attribut n'a d'existence pour cet élément dans le modèle de structure que lorsqu'il est explicitement rajouté. Notez que l'attribut nodeValue de l'instance Attribut peut aussi être utilisée pour récupérer la forme textuelle de la (les) valeurs des l'attributs.

En XML, où la valeur d'un attribut peut contenir des références d'entités, les noeuds enfants du noeud Attr fournissent une représentation dans laquelle les références d'entités ne sont pas résolues. Ces noeuds enfants peuvent être soit de type Text soit de type EntityReference. Puisque le type des attributs pourrait être inconnu, aucune valeur d'attribut n'est atomisée.

Définition IDL
interface Attribut: noeud {
  readonly attribute  DOMString    name;
  readonly attribute  boolean      specified;
           attribute  DOMString    value;
};
            
Attributs
name
Retourne le nom de l'attribut courant.
specified
Prend la valeur true si une valeur a été explicitement donnée à l'attribut courant dans le document original ; false sinon. Notez que c'est l'implémentation qui se charge de calculer cette valeur, et non l'utilisateur. Si l'utilisateur change la valeur de l'attribut (même si ce dernier se retrouve avec la même valeur que sa valeur par défaut) alors la valeur de specified est automatiquement mise à true. Pour re-initialiser l'attribut à la valeur par défaut définie dans la DTD, l'utilisateur doit le supprimer. L'implémentation rendra alors disponible un nouvel attribut pour lequel specified sera mis à false et aura la valeur par défaut (si il en existe une).

En résumé :

  • Si l'attribut a une valeur spécifiée dans le document, specified vaut true, et la valeur de l'attribut est égale à la valeur spécifiée.
  • Si l'attribut n'a pas de valeur spécifiée dans le document mais qu'il existe une valeur par défaut définie dans la DTD, alors specified vaut false, et la valeur de l'attribut est égale à la valeur par défaut de la DTD.
  • Si l'attribut n'a pas de valeur spécifiée dans le document et qu'il n'a pas de valeur déclarée dans la DTD (attribut déclaré #IMPLIED dans la DTD), alors l'attribut n'apparaît pas dans le modèle de structure du document.
value
A l'utilisation, la valeur de l'attribut est retournée comme une chaîne de caractères. Les entités caractères et les entités générales de référence sont remplacées par leurs valeurs.

A l'initialisation, un noeud Text est créé avec comme contenu la chaîne de caractère qui sera considérée telle qu'elle se présente sans analyse lexico-syntaxique et ceci même si elle contient des balises.

Interface Elément

Les objets les plus couramment rencontrés par les utilisateurs parcourant un document (mis à part le texte lui-même) sont de loin les noeuds d'éléments (Element). Considérez le document XML suivant :

<elementExample id="demo">
  <subelement1/>
  <subelement2><subsubelement/></subelement2>
</elementExample>  

Représenté en DOM, le noeud sommet est le noeud Element pour "elementExample", contenant deux noeuds Element enfants, l'un pour l'élément "subelement1" et l'autre pour l'élément "subelement2". "subelement1" ne contient pas de noeud enfant.

Des attributs peuvent être associés aux éléments. Puisque l'interface Element hérite de celui de Node, la méthode générique getAttributes de l'interface Node peut être utilisée pour récupérer l'ensemble des tous les attributs d'un élément. Il existe des méthodes de l'interface Element pour récupérer soit un objet Attr à partir de son nom, soit une valeur d'attribut à partir de son nom. En XML, où la valeur de l'attribut peut contenir des références à des entités, un objet Attr doit pouvoir être récupéré pour examiner l'éventuel sous-arbre, potentiellement complexe, représentant la valeur de l'attribut. D'un autre côté, en HTML, où tous les attributs ne reçoivent que des chaînes textuelles simples, les méthodes pour récupérer directement les valeurs d'attributs peuvent être utilisées en toute sécurité et commodité.

Définition IDL
interface élément : Node {
  readonly attribute  DOMString            tagName;
  DOMString       getAttribute(in DOMString name);
  void            setAttribute(in DOMString name, 
                               in DOMString value)
                               provoque (DOMException);
  void             removeAttribute(in DOMString name)
                                   provoque (DOMException);
  Attribut         getAttributeNode(in DOMString name);
  Attribut         setAttributeNode(in nouvelAttribut)
                                    provoque (DOMException);
  Attribut         removeAttributeNode(in oldAttribut)
                                       provoque (DOMException);
  NodeList         getElementsByTagName(in DOMString name);
  void             normalize();
};
            
Attributs
tagName
Le nom de l'élément. Par exemple, dans :
<elementExample ID="demo"> 
        ... 
</elementExample> ,
la valeur de tagName est "elementExample". Notez que ce nom est sensible à la casse en XML, comme le sont tous les traitements de DOM. Le DOM HTML retourne le nom (tagName)d'un élément HTML sous la forme canonique majuscule, indépendamment de la casse utilisée dans le document source.
Méthodes
getAttribute
Permet d'obtenir une valeur d'attribut à partir du nom de l'attribut.
Paramètres
name

Le nom de l'attribut à récupérer.

Valeur retournée
La valeur de l'attribut Attr sous la forme d'une chaîne de caractères, ou une chaîne vide si cet attribut n'a ni valeur spécifiée ni valeur par défaut.

Cette méthode ne provoque aucune exception.
setAttribute
Ajoute un nouvel attribut. Si un attribut de même nom existe déjà au niveau de l'élément, sa valeur est changée par celle passée en paramètre. Cette valeur est une chaîne de caractères simple, elle n'est pas validée au moment de l'initialisation. Donc, tout balisage (comme par exemple une référence à une entité) est traité littéralement et doit être correctement préservé par l'implémentation quand il doit être écrit. En vue d'assigner une valeur d'attribut contenant des références à des entités, l'utilisateur doit créer un noeud Attr ainsi que tous les noeuds de type Text et EntityReference, construire le sous-arbre approprié, et utiliser la méthode setAttributeNode pour les définir comme étant des valeurs d'attributs.
Paramètres
name

Le nom de l'attribut à créer ou modifier.

Value

Valeur textuelle à mettre comme valeur d'attribut .

Exceptions
DOMException

INVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère non valide.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
removeAttribute
Supprime un attribut spécifié par son nom. Si l'attribut supprimé a une valeur par défaut, il est alors immédiatement remplacé.
Paramètres
name

Le nom de l'attribut à retirer

Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Cette méthode ne retourne rien.
getAttributeNode
Permet d'obtenir un noeud de type Attr à partir de son nom.
Paramètres
nom

Le nom de l'attribut à récupérer.

Valeur retournée
Le noeud de type Attr dont le nom est celui spécifié ou null si il n'y a pas d'attribut de ce nom.

Cette méthode ne provoque aucune exception.
setAttributeNode
Rajoute un nouvel attribut. Si un attribut de ce nom est déjà présent dans l'élément, il est remplacé par le nouveau.
Paramètres
newAttr

Le noeud Attr à ajouter à la liste des attributs.

Valeur retournée
Si le nouvel attribut newAttr remplace un attribut existant de même nom, le noeud attribut Attr précédemment existant est retourné, sinon la valeur null est retournée.
Exceptions
DOMException

WRONG_DOCUMENT_ERR : provoquée si le nouvel attribut nouvelAttribut a été créé dans un autre document que celui contenant l'élément auquel on l'applique.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.

INUSE_ATTRIBUTE_ERR : provoquée si nouvelAttribut est déjà un attribut d'un autre objet de type Element. L'utilisateur de DOM doit explicitement cloner les noeuds Attr pour les réutiliser dans d'autres éléments.


removeAttributeNode
Supprime l'attribut spécifié.
Paramètres
oldAttr

Le noeud Attr à supprimer de la liste d'attributs. Si l'objet Attr retiré a une valeur par défaut déclarée, il est immédiatement remplacé.

Valeur retournée
Le noeud Attr qui a été supprimé.
Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.

NOT_FOUND_ERR : provoquée si oldAttribut n'est pas un attribut de l'élément.


getElementsByTagName
Retourne une liste de noeuds (NodeList) de tous les éléments descendant ayant un nom donné, organisés selon l'ordre dans lequel ils pourraient apparaître dans un parcours de préfixé de l'arbre des objets Element.
Paramètres
name

Le nom de l'élément à trouver. La valeur spéciale "*" concorde avec tous les éléments.

Valeur retournée
Une liste concordante de noeuds de type Element.

Cette méthode ne provoque aucune exception.
normalize
Mets tous les noeuds Text dans toute la profondeur du sous-arbre en dessous de l'objet de type Element courant sous une forme "normale" dans laquelle seul le balisage (c'est à dire les balises, les commentaires, les instructions de traitements, les sections CDATA, et les références d'entités) sépare les noeuds Text. Autrement dit, il ne doit pas y avoir de noeuds de type Text adjacents. Cela peut être utilisé pour garantir que la vue DOM d'un document soit la même que si elle avait été sauvegardée et rechargée, et est aussi utile lorsque des opérations (telles que des projections XPointer) qui dépendent directement de l'arbre de structure spécifique à un document doivent être utilisées.
Cette méthode n'a pas de paramètre.
Cette méthode ne retourne rien.
Cette méthode ne provoque aucune exception.
Interface Text

L'interface Text représente le contenu textuel (connu sous le nom de données caractères dans XML) d'un objet de type Element ou Attr. Si il n'y a pas de balisage dans le contenu d'un élément, le texte est contenu dans un objet unique implémentant l'interface Text qui est l'enfant unique de l'élément. Si il y a du balisage, il est analysé syntaxiquement et transformé en une liste d'éléments et de noeuds Text qui forment la liste des enfants de l'élément courant.

Quand un document est d'abord accessible via DOM, il n'y a qu'un seul noeud de type Text pour chaque bloc de texte. Les utilisateurs peuvent créer des noeuds adjacents qui représentent les contenus d'un élément donné sans que du balisage ne survienne dans le texte, mais ils doivent savoir qu'il n'y a aucun moyen en XML ou HTML pour représenter les séparations entre ces noeuds Aussi, ils ne pourront pas (en général) être persistants entre deux sessions DOM. La méthode normalize() appliquée à des objets de type Element fusionne tous les objets Text adjacents pour ne former qu'un seul objet pour chaque bloc de texte. Cela est recommandé avant l'utilisation d'opérations dépendant d'une structure de document particulière, telle que la navigation avec XPointers.

Définition IDL
interface Texte : CharacterData {
  Texte           splitText(in unsigned long offset)
                            provoque (DOMException);
};
            
Méthodes
splitText
Coupe un noeud textuel en deux au niveau du décalage spécifié, en conservant les deux noeuds de type Text résultants comme étant deux noeuds frères dans l'arbre. Le noeud courant ne contient plus que les caractères se trouvant avant le point de coupure. Et un nouveau noeud de type Text, qui est inséré comme noeud frère suivant le noeud courant, contient tous les caractères à partir du point de coupure (inclus) et jusqu'à la fin.
Paramètres
offset

Le décalage où il faut couper le noeud textuel en deux, en commençant à 0.

Valeur retournée
Le nouveau noeud textuel.
Exceptions
DOMException

INDEX_SIZE_ERR : provoquée si le décalage spécifié est négatif ou plus grand que le nombre de caractères dans les données.

NO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.


Interface Comment

Cette interface représente le contenu d'un commentaire, c'est à dire tous les caractères compris entre les caractères de début '<!--' et de fin '-->'. Notez que cela est la définition d'un commentaire en XML, et, en pratique, HTML, quoique certains outils HTML puissent implémenter la totalité de la structure commentaire de SGML.

Définition IDL
interface Comment : CharacterData {
};
            

1.3. Interfaces étendues

Les interfaces définis ici font partie des spécifications du noyau de DOM niveau 1, mais les objets qui ont ces interfaces ne seront jamais rencontrés dans une implémentation de DOM limitée au seul HTML. En ce sens, les réalisations qui ne concernent que HTML n'ont pas besoin d'implémenter ces interfaces.

Interface CDATASection

Les sections CDATA sont utilisées pour protéger des caractères de balisage dans des portions de textes. Le seul délimiteur reconnu dans une section CDATA est la chaîne "]]>" qui ferme les sections CDATA. Les sections CDATA ne peuvent pas être imbriquées les unes dans les autres. L'objectif premier est d'inclure tel quel des fragments XML, sans avoir à protéger tous les délimiteurs propres au langage.

Le texte contenu dans la section CDATA est stocké dans l'attribut DOMString du noeud Text. Notez que celui-là est susceptible de contenir des caractères qui auraient besoin d'être protégés en dehors d'une section CDATA et que, en fonction de l'encodage des caractères choisi, il pourrait être impossible d'écrire en sortie certains caractères faisant partie d'une section CDATA.

L'interface CDATASection hérite de l'interface CharacterData au travers de l'interface Text. Les noeuds de type CDATASections adjacents ne sont pas fusionnés par la méthode de normalisation Element.normalize().

Définition IDL
interface CDATASection : Text {
};
            
Interface DocumentType

Chaque Document a un attribut doctype dont la valeur est soit null soit un objet DocumentType. L'interface DocumentType du noyau de DOM niveau 1 fournit une interface pour la liste des entités définies pour le document, et un peu plus par l'effet des espaces de noms et des différents travaux fait sur XML quant à la représentation des DTD et dont les résultats ne sont pas complètement connus au moment où ces lignes sont écrites.

DOM niveau 1 ne supporte pas l'édition des noeuds de type DocumentType.

Définition IDL
interface DocumentType : Node {
  readonly attribute  DOMString           name;
  readonly attribute  NameNodeMap         entities;
  readonly attribute  NameNodeMap         notations;
};
            
Attributs
name
Le nom de la DTD ; plus précisément, il s'agit du nom qui suit immédiatement le mot-clé DOCTYPE.
entities
Il s'agit d'un NameNodeMap contenant les entités générales, à la fois externes et internes, déclarées dans la DTD. Les doublons sont ignorés. Par exemple, dans :
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY % baz "baz">
]>
<ex/>
l'interface fournit un accès aux entités générales foo et bar mais pas à baz qui est une entité paramètre. Chaque noeud de cette table de correspondance implémente l'interface Entity.

Le DOM niveau 1 ne supporte pas l'édition des entités, par conséquent, les entités ne peuvent en aucun cas être altérées.

notations
Il s'agit d'un NameNodeMap contenant les notations déclarées dans la DTD. Les doublons sont ignorés. Chaque noeud de cette table de correspondance implémente l'interface Notation.

Le DOM niveau 1 ne supporte pas l'édition des notations, par conséquent, les notations ne peuvent en aucun cas être altérées.

Interface Notation

Cette interface représente une notation déclarée dans la DTD. Une notation sert, soit pour déclarer par un nom, le format d'une entité non contrôlée par validateur lexico-syntaxique (reportez vous à la section 4.7 de la spécification XML 1.0), soit pour des déclarations formelles de cibles d'instructions de traitement (reportez vous à la section 2.6 de la spécification XML 1.0). L'attribut nodeName hérité de l'interface Node prend comme valeur le nom déclaré de la notation.

Le DOM niveau 1 ne supporte pas l'édition des noeuds Notation ; par conséquent, ils sont seulement autorisés en lecture seule.

Un noeud Notation n'a aucun parent.

Définition IDL
interface Notation : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
};
            
Attributs
publicId
L'identificateur publique de cette notation. Si l'identificateur publique n'est pas précisé dans la DTD, alors cet attribut prend la valeur null.
systemId
L'identificateur système de cette notation. Si l'identificateur système n'est pas précisé dans la DTD, alors cet attribut prend la valeur null.
Interface Entity

Cette interface représente n'importe quelle entité d'un document XML qu'elle soit analysable ou non par le parseur. Notez que l'interface modélise l'entité elle-même et non sa déclaration. La modélisation des déclarations d'entités a été laissée de côté pour un autre niveau de spécification de DOM.

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

Un processeur XML peut choisir de faire une résolution complète des entités avant que le modèle de structure ne soit passé au DOM. Dans ce cas, il n'y aura aucun objet EntityReference dans l'arbre du document.

XML ne requiert pas qu'un processeur XML non-validant sache lire et traiter les déclarations d'entités faites dans le sous-ensemble externe ou déclarées dans des entités paramètre externes. Cela signifie que les entités validées déclarées dans le sous-ensemble de déclarations externes n'ont pas besoin d'être étendue par certains types d'applications, et que la valeur de remplacement de l'entité peut ne pas être disponible. Quand la valeur de remplacement est disponible, la liste des enfants correspondant au noeud Entity représente la structure de ce texte de remplacement. Autrement, la liste des enfants est vide.

La résolution des enfants de l'entité (la valeur de remplacement) peut être "mollement" évaluée. Des actions de l'utilisateur (tel que l'appel de la méthode childNodes sur le noeud Entity) sont supposées déclencher l'évaluation.

DOM niveau 1 ne supporte pas l'édition des noeuds Entity. Si un utilisateur souhaite faire des changements sur le contenu d'un objet Entity, chacun des noeuds EntityReference correspondant doit être remplacé dans le modèle de structure, par un clone du contenu de l'objet Entity, et le changement doivent ainsi être opérés sur chacun de clones. Tous les descendants d'un noeud de type Entity sont en lecture seule.

Un noeud Entity n'a aucun parent.

Définition IDL
interface Entity : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
  readonly attribute  DOMString            notationName;
};
            
Attributs
publicId
L'identificateur publique associé à l'entité. Si cet identificateur n'est pas spécifié, cette valeur est null.
systemId
L'identificateur système associé à l'entité. Si cet identificateur n'est pas spécifié, cette valeur est null.
notationName
Pour les entités qui ne peuvent pas passer au contrôleur lexico-syntaxique, cet attribut contient le nom de la notation associée à l'entité. Pour les entités contrôlées, cette valeur est null.
Interface EntityReference

Les objets de type EntityReference peuvent être insérés dans le modèle de structure quand une référence d'entité se trouve dans le document source, ou quand l'utilisateur souhaite insérer une référence d'entité. Notez que les références de caractères et les références d'entités pré-définies sont supposées être résolues par les processeurs HTML ou XML. Ces caractères sont ainsi représentés par leur équivalent Unicode plutôt que par une référence d'entité. De plus, le processeur XML peut complètement étendre les références aux entités pendant la phase de construction du modèle de structure, au lieu de fournir des objets EntityReference. Si de tels objets sont fournis, alors, pour un noeud EntityReference donné, il se pourrait qu'il n'y ait aucun noeud Entity représentant l'entité référencée. Par contre si un tel noeud Entity existe, alors la liste enfant de l'objet EntityReference est la même que pour le noeud Entity. Comme avec le noeud Entity, tous les descendants de l'objet EntityReference sont en lecture seule.

La résolution des enfants de l'objet EntityReference (la valeur de remplacement de l'objet Entity référencé) peut être"mollement" évaluée ; des actions de l'utilisateur (comme par exemple l'appel de la méthode childNodes appliquée au noeud de type EntityReference) sont supposées déclencher l'évaluation.

Définition IDL
interface entityReference : Node {
};
            
Interface ProcessingInstruction

L'interface ProcessingInstruction représente une "instruction de traitement", utilisée en XML comme un moyen pour conserver des informations spécifiques à un processeur dans le texte même du document.

Définition IDL
interface ProcessingInstruction : Node {
  readonly attribute  DOMString          target;
           attribut  DOMString           data;
                                      // provoque une DOMException  à l'initialisation
};
            
Attributs
target
La cible de cette instruction de traitement. XML définit la cible comme étant la première unité lexicale suivant la balise commençant l'instruction de traitement.
data
Le contenu de cette instruction de traitement. Cela va du premier caractère non-blanc suivant la cible au dernier caractère précédant les caractères ?> de fermeture de l'instruction de traitement.
Exceptions à l'initialisation
DOMException

NO_MODIFICATION_ALLOWED : provoquée quand le noeud est en lecture seule .