 |
 |
 |
|
|
|
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.
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 :
Document
-- Element
(un au plus), ProcessingInstruction,
Comment,
DocumentTypeDocumentFragment
-- Element, ProcessingInstruction,
Comment, Text, CDATASection, EntityReferenceDocumentType
-- pas d'enfantEntityReference
-- Element,
ProcessingInstruction,
Comment,
Text,
CDATASection,
EntityReferenceElement --
Element, Text, Comment, ProcessingInstruction,
CDATASection,
EntityReferenceAttr -- Text, EntityReferenceProcessingInstruction
-- pas d'enfantComment
-- pas d'enfantText -- pas
d'enfantCDATASection
-- pas d'enfantEntity
-- Element,
ProcessingInstruction,
Comment,
Text,
CDATASection,
EntityReferenceNotation --
pas d'enfantDe 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.
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.
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é.
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.
DOMStringPour garantir l'interopérabilité, DOM spécifie le type
DOMString comme suit :
DOMString est une séquence de caractères codés sur
16-bits. Cela peut être exprimé en terme d'IDL par :
typedef sequence<unsigned short> DOMString;
DOMString en utilisant
UTF-16 (définit dans l'annexe C.3 de [UNICODE] et l'amendement 1 de
[ISO-10646]). L'encodage UTF-16 fut choisi parce qu'il s'agit d'un
standard largement utilisé dans l'industrie. Notez bien que pour HTML et
XML, le jeu de caractères des documents (et par conséquent la notation des
références numériques aux caractères) est basée, dans les deux cas, sur
UCS-4. Par conséquent, une même référence numérique de caractère dans un
document source peut, dans certains cas, correspondre à deux positions
consécutives dans un DOMString (l'octet de poids fort et
celui de poids faible). Note : même si DOM attribut le type
DOMString pour les chaînes de caractères, les implémentations de DOM
peuvent utiliser des noms différents. Par exemple, en Java,
DOMString correspond au type String parce que
lui aussi est encodé en UTF-16.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.
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.
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.
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;
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 |
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.
interface DOMImplementation {
boolean hasFeature(in DOMString feature, in DOMString version);
};
hasFeaturefeature |
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 si la caractéristique est
implantée dans la version spécifiée,
false sinon.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().
interface DocumentFragment : Node {
};
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.
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);
};
doctypeDocumentType)
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é.implementationDOMImplementation
qui gère le document. Une application DOM peut utiliser des
objets de différentes implémentations.documentElementtagName) est "HTML".createElementElement, donc
les attributs peuvent être spécifiés directement sur l'objet
retourné.
tagName |
Le nom du type de l'élément à instancier.
Pour XML, il est sensible à la casse. Pour
HTML, le paramètre |
Element.DOMExceptionINVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère invalide.
createDocumentFragmentDocumentFragment
vide.
DocumentFragment.createTextNodecreateCommentcreateCDATASectionCDATASection
dont la valeur est la chaîne de caractères spécifiée.
data |
Les données formant le contenu de la
section |
CDATASection.DOMExceptionNOT_SUPPORTED_ERR : provoquée si le document est un document HTML.
createProcessingInstructionProcessingInstruction
ayant le nom et les chaînes de caractères de données
spécifiés.
target |
La partie cible de l'instruction de traitement. |
|
data |
Les données du noeud |
ProcessingInstruction.DOMExceptionINVALID_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.
createAttributAttr
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.
name |
Le nom de l'attribut. |
Attr.DOMExceptionINVALID_CHARACTER_ERR : provoquée si le nom spécifié contient un caractère non valide.
createEntityReferenceEntityReference.
name |
Le nom de l'entité à référencer. |
EntityReference.DOMExceptionINVALID_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.
getElementsByTagNameNodeList
(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.
tagName |
Le nom de l'élément à trouver. La valeur spéciale "*" signifie qu'il faut chercher tous les éléments. |
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.
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);
};
Un entier indique le type de noeud dont il s'agit.
| ELEMENT_NODE | Le noeud est un |
| ATTRIBUTE_NODE | Le noeud est un Attr. |
| TEXT_NODE | Le noeud est un |
| CDATA_SECTION_NODE | Le noeud est une |
| ENTITY_REFERENCE_NODE | Le noeud est une |
| ENTITY_NODE | Le noeud est une |
| PROCESSING_INSTRUCTION_NODE | Le noeud est une |
| COMMENT_NODE | Le noeud est un |
| DOCUMENT_NODE | Le noeud est un |
| DOCUMENT_TYPE_NODE | Le noeud est un |
| DOCUMENT_FRAGMENT_NODE | Le noeud est un |
| NOTATION_NODE | Le noeud est une |
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 |
nodeNamenodeValueDOMExceptionNO_MODIFICATION_ALLOWED_ERR : provoquée lorsque le noeud est en lecture seule.
DOMExceptionDOMSTRING_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.
nodeTypeparentNodeDocument,
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.childNodesNodeList)
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.firstChildnull est retournée.lastChildnull est retournée.previousSiblingnull est
retournée.nextSiblingnull est
retournée.attributesNameNodeMap
contenant les attributs de ce noeud (si c'est un Element)
ou null sinon.ownerDocumentDocument
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.insertBeforenewChild 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é.
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é. |
DOMExceptionHIERARCHY_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.
replaceChildoldChild 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é.
newChild |
Le nouveau noeud à mettre dans la liste des enfants. |
|
oldChild |
Le noeud à remplacer dans la liste. |
DOMExceptionnewChild, 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.
removeChildoldChild de la liste des
enfants, et le retourne.
oldChild |
Le noeud à retirer. |
DOMExceptionNOT_FOUND_ERR : provoquée si
oldChild n'est pas un enfant du
noeud courant.
appendChildnewChild à la fin de la liste
des noeuds enfants du noeud courant. Si
newChild est déjà dans l'arbre, il est d'abord
retiré.
newChild |
Le noeud à rajouter. Si |
DOMExceptionnewChild, 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.
hasChildNodestrue si le noeud a un enfant,
false sinon.cloneNodeparentNode 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.
deep |
Si Si |
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.
interface NodeList{
Node item(in unsigned long index);
readonly attribute unsigned long length;
};
itemindex. Si
index est supérieure ou égale au nombre de
noeuds de la collection, la méthode retourne la valeur
null.
index |
La position dans la collection. |
index dans la NodeList, ou
null si la valeur du paramètre
index n'est pas valide.lengthindex va de 0 à
length-1 inclus.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.
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;
};
getNamedItemname |
Nom du noeud à obtenir. |
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.setNamedItemnodeName.
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.
arg |
Un noeud à stocker dans une
table de noeuds nommés. Le noeud sera plus
tard accessible en utilisant la valeur de son
attribut |
Node
remplace un noeud existant ayant le même nom, le Node
remplacé est retourné , sinon la valeur retournée est
null.DOMExceptionWRONG_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.
removeNamedItemAttr
ayant une valeur par défaut, il est immédiatement remplacé.
name |
Le nom du noeud à retirer. |
null si aucun noeud de ce nom
n'existe dans cette table.DOMExceptionNOT_FOUND_ERR : provoquée si il n'y a pas
dans la table de noeud ayant le nom
name.
itemindex 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.
index |
La position dans la table. |
NameNodeMap se
trouvant à la position spécifiée par
index , ou null si la valeur
de index n'est pas valide.lengthindice peut varier de 0 à
length-1 inclus.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.
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);
};
dataCharacterData.
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.
DOMExceptionNO_MODIFICATION_ALLOWED_ERR : provoquée quand le noeud est en lecture seule .
DOMExceptionDOMSTRING_SIZE_ERR : provoquée si la taille
de la donnée retournée dépasse la capacité du
type DOMString de
l'implémentation.
lengthdata 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.substringDataoffset |
décalage de départ de la sous-chaîne à extraire. |
count |
Le nombre de caractères à extraire. |
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.DOMExceptionINDEX_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.
appendDatadata permet d'avoir accès à la concaténation
des données data et de la variable
DOMString spécifiée.
arg |
La |
DOMExceptionNO_MODIFICATION_ALLOWED_ERR : provoquée si le noeud est en lecture seule.
insertDataoffset |
Le décalage de caractère spécifiant l'endroit où il faut insérer la chaîne. |
arg |
La |
DOMExceptionINDEX_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.
deleteDatadata et length sont mis
à jour en fonction de la modification effectuée.
offset |
Le décalage à partir duquel il faut retirer des caractères. |
|
|
Le nombre de caractères à supprimer. Si
la somme de |
DOMExceptionINDEX_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.
replaceDataoffset |
Le décalage à partir d'où il faut commencer le remplacement. |
count |
Le nombre de caractères à
remplacer. Si la somme de |
arg |
La variable
|
DOMExceptionINDEX_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.
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.
interface Attribut: noeud {
readonly attribute DOMString name;
readonly attribute boolean specified;
attribute DOMString value;
};
namespecifiedtrue 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é :
specified vaut true, et la
valeur de l'attribut est égale à la valeur
spécifiée.specified vaut
false, et la valeur de l'attribut est égale
à la valeur par défaut de la DTD.valueA 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.
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é.
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();
};
tagName<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.getAttributename |
Le nom de l'attribut à récupérer. |
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.setAttribute