Referenz der Klassen-API von DOM

(Auszug aus "Perl & XML" von Erik T. Ray & Jason McIntosh)

DOM entwickelt sich mehr und mehr zur bevorzugten Schnittstelle in der Perl-XML-Welt. Aus diesem Grund lohnt sich eine ausführliche Betrachtung. In den folgenden Abschnitten beschreiben wir je eine Klasse, ihren Zweck sowie ihre Properties und Methoden.

Achtung! Die DOM-Spezifikation schlägt UTF-16 als Standardcodierungssystem vor. Die meisten Perl-Implementierungen basieren aber auf UTF-8. Mit den aktuellen Versionen von Perl ist es eher schwierig, mit Zeichen einer anderen Länge als 8 Bit zu arbeiten. In zukünftigen Versionen wird sich die Situation wohl verbessern, und es dürfte kein Problem mehr sein, mit UTF-16 zu arbeiten.

Document

Die Klasse Document ist für die Kontrolle des Dokuments in seiner Gesamtheit zuständig. Sie kann neue Objekte erzeugen und bietet Zugriff auf abstrakte Informationen wie die Dokumenttypdeklaration oder das Wurzelelement.

Properties

doctype
Die Dokumenttypdeklaration (DTD).

documentElement
Das Wurzelelement des Dokuments.

Methoden

createElement, createTextNode, createComment, createCDATASection, createProcessingInstruction, createAttribute, createEntityReference
Diese Methoden erzeugen je ein neues Objekt des entsprechenden Typs.

createElementNS, createAttributeNS (nur DOM2)
Diese Methoden entsprechen den Methoden createElement und createAttribute, erhalten aber neben dem Namen des Elements bzw. Attributs ein weiteres Argument, nämlich den Namensraum.

createDocumentFragment
Erzeugt ein Containerobjekt für einen Teilbaum des Dokuments.

getElementsByTagName
Das Ergebnis der Methode ist eine NodeList mit allen Kindelementen eines Knotens, die einen gegebenen Elementnamen haben.

getElementsByTagNameNS (nur DOM2)
Entspricht der Methode getElementsByTagName, erhält aber neben dem gewünschten Elementnamen ein weiteres Argument, nämlich den Namensraum. Der Asterisk (das Zeichen *) dient als Wildcard für beliebige Elementnamen bzw. Namensräume.

getElementById (nur DOM2)
Sucht nach dem Element mit einem vorgegebenen Wert im ID-Attribut.

importNode (nur DOM2)
Kopiert einen Knoten, der aus einem anderen Dokument stammen darf. Man kann sich das wie Kopieren aus dem »Clipboard« vorstellen, bei dem Markup importiert wird.

DocumentFragment

Die Klasse DocumentFragment kann ein Dokumentfragment aufnehmen. Ein Objekt dieses Typs hat eine Liste von beliebig vielen Kindknoten, die jeweils einen Teilbaum des Dokuments enthalten. Im Unterschied zur Klasse Document darf es mehr als ein Kindknoten vom Typ Element sein. Ein DocumentFragment unterliegt in dieser Beziehung nicht den Wohlgeformtheitsregeln, die aber in allen anderen Punkten (Sonderzeichen in Text usw.) sehr wohl gelten.

Die Klasse besitzt keine spezifischen Methoden oder Properties. Allerdings erbt sie die generischen Methoden der Klasse Node zum Zugriff auf die Kindknoten.

DocumentType

Diese Klasse bietet Zugriff auf die in der Dokumenttypdeklaration zu Beginn des Dokuments enthaltene Information, allerdings nur auf den internen Bereich.

Für diese Klasse sind keine spezifischen Methoden definiert, allerdings einige Properties. Diese sind allesamt Read-only.

Properties

name
Der Name des Wurzelelements.

entities
Eine NamedNodeMap, deren Elemente Entitydeklarationen sind.

notation
Eine NamedNodeMap, deren Elemente Deklarationen von Notationen sind.

internalSubset (nur DOM2)
Der interne Bereich der DTD als String.

publicId (nur DOM2)
Der öffentliche Bezeichner des externen Bereichs der DTD.

systemId (nur DOM2)
Der Systembezeichner des externen Bereichs der DTD.

Node

Alle anderen Klassen sind von der Klasse Node abgeleitet. Die von dieser Klasse implementierten Properties und Methoden stehen bei allen DOM-Objekten zur Verfügung. Einige Properties sind je nach Knotentyp undefiniert, zum Beispiel der Wert eines Elements. Die generischen Knoten dieser Klasse sind nützlich, wenn man Code schreibt, der für Knoten verschiedener Typen funktionieren soll. Wenn man dagegen mit bestimmten Knotentypen arbeitet, sind die spezifischen Methoden der entsprechenden Klasse meistens angenehmer und einfacher.

Alle Properties dieser Klasse mit Ausnahme von nodeValue und prefix sind Read-only.

Properties

node Name
Eine Property, die für Elemente, Attribute und Entities definiert ist. Im Falle von Elementen enthält sie zum Beispiel den Elementnamen.

nodeValue
Eine Property, die für Attribute, Textknoten, CDATA-Abschnitte, Verarbeitungsanweisungen und Kommentare definiert ist.

nodeType
Enthält einen der folgenden Knotentypen: Element, Attr, Text, CDATASection, EntityReference, Entity, ProcessingInstruction, Comment, Document, DocumentType, DocumentFragment oder Notation.

parentNode
Eine Referenz auf den Vaterknoten.

childNodes
Eine geordnete Liste mit Referenzen auf die Kindknoten (sofern vorhanden) dieses Knotens.

firstChild, lastChild
Referenzen auf den ersten und den letzten Kindknoten (sofern vorhanden).

previousSibling, nextSibling
Der Vorgänger bzw. Nachfolger dieses Knotens.

attributes
Eine ungeordnete Liste (NamedNodeMap) von Knoten, die Attribute dieses Knotens sind (sofern vorhanden).

ownerDocument
Eine Referenz auf den Dokumentknoten – wird speziell benötigt, wenn man einen neuen Knoten erzeugen will.

namespaceURI (nur DOM2)
Falls dieser Knoten ein Namensraumpräfix hat, dann enthält diese Property den URI des zugehörigen Namensraums, anderenfalls null.

prefix (nur DOM2)
Ein eventuelles Namensraumpräfix.

Methoden

insertBefore
Fügt einen neuen Kindknoten als Vorgänger eines gegebenen Kindknotens ein.

replaceChild
Ersetzt einen vorhandenen Kindknoten durch einen neuen; zurückgegeben wird der alte.

appendChild
Hängt einen neuen Knoten an das Ende der Kindknotenliste an.

hasChildNodes
Liefert wahr, falls dieser Knoten Kinder besitzt, anderenfalls falsch.

cloneNode
Erzeugt eine Kopie dieses Knotens. Dies stellt eine alternative Möglichkeit dar, neue Knoten zu beschaffen. Die Properties des neuen Knotens entsprechen denen des alten, mit Ausnahme von parentNode, previousSibling usw., die alle undefiniert sind. Die Attribute geklonter Elemente stimmen dagegen mit denen des Originals überein. Die Methode besitzt ein Argument namens deep. Steht dieses auf wahr, dann werden auch Kindknoten (inkl. deren Kindknoten) usw. kopiert, anderenfalls enthält die Property childNodes eine leere Liste.

hasAttributes (nur DOM2)
Ergibt wahr, falls dieser Knoten Attribute besitzt.

isSupported (nur DOM2)
Ergibt wahr, falls diese DOM-Implementierung ein angegebenes Feature unterstützt.

NodeList

Diese Klasse ist ein Container für eine geordnete Liste von Knoten. Die Liste ist »live«, man kann sie also verändern und damit unmittelbar auch das Dokument entsprechend verändern.

Properties

length Die Anzahl von Knoten in der Liste.

Methoden

item
Ergibt eine Referenz auf den Knoten mit der Nummer n innerhalb der Liste. Die Zahl n ist das Argument der Methode (wobei Null für den ersten Knoten steht).

NamedNodeMap

Dies ist eine ungeordnete Knotenmenge, die den Zugriff auf Knoten über ihren Namen erlaubt. Zum Zweck der Aufzählung ist es auch möglich, die Knoten über eine Indexnummer zu adressieren, aber dieser Index impliziert keine Ordnung (zumindest keine auf die man sich verlassen könnte).

Properties

length
Die Anzahl der Knoten in der Liste.

Methoden

getNamedItem, setNamedItem
Ergibt bzw. setzt einen bestimmten Knoten, dessen Name ggf. aus der nodeName -Property gelesen wird.

removeNamedItem
Entfernt den Knoten mit dem angegebenen Namen aus der Liste und gibt ihn zurück.

item
Ergibt den Knoten mit der Nummer n innerhalb der Knotenliste. Beachten Sie, daß diese Methode nur die Iteration über die Liste ermöglichen soll und keine Ordnung impliziert.

getNamedItemNS (nur DOM2)
Liefert den Knoten mit dem angegebenen voll qualifizierten Namen (d. h. einer Kombination aus Namensraum und lokalem Namen).

removeNamedItemNS (nur DOM2)
Entfernt das Element mit dem angegebenen voll qualifizierten Namen aus der Liste.

setNamedItemNS (nur DOM2)
Setzt den Knoten mit dem angegebenen voll qualifizierten Namen.

CharacterData

Diese Klasse erweitert Node um den Zugriff auf enthaltene Zeichendaten. Davon abgeleitete Klassen sind Text, CDATASection, Comment und ProcessingInstruction.

Properties

data
Die enthaltenen Zeichendaten.

length
Die Anzahl der Zeichen in der Property data.

Methoden

appendData
Hängt einen String an das Ende der data-Property an.

substringData
Extrahiert einen Teilstring aus der Property data, der die Zeichen von offset bis offset + count enthält.

insertData
Fügt einen String in die data-Property an der Stelle offset ein.

deleteData
Setzt die Property data auf den Leerstring zurück.

replaceData
Ersetzt einen Teilstring der Property data.

Element

Dies ist der wichtigste Knotentyp, mit dem Sie in den meisten Fällen arbeiten werden. Ein Element kann andere Knoten als Kinder enthalten, vor allem aber auch Attributknoten.

Properties

tagname
Der Name des Elements.

Methods

getAttribute, getAttributeNode
Liefert den Wert des Attributs bzw. den Attributknoten mit dem angegebenen Namen.

setAttribute, setAttributeNode
Setzt den Wert des Attributs bzw. den Attributknoten mit dem angegebenen Namen.

removeAttribute, removeAttributeNode
Entfernt den Attributknoten mit dem angebenen Namen bzw. den angegebenen Attributknoten aus dem Element. Das Ergebnis der Methode ist der entfernte Knoten.

getElementsByTagName
Gibt eine NodeList mit allen enthaltenen Elementen zurück, die einen angegebenen Namen tragen.

normalize
Prinzipiell kann eine Kindknotenliste mehrere aufeinanderfolgende Textknoten enthalten. Diese Methode macht daraus einen einzigen Textknoten. Das ist zum Beispiel nützlich, wenn man Knoten vergleichen will. 

getAttributeNS (nur DOM2)
Liefert den Wert des Attributknotens mit dem angegebenen voll qualifizierten Namen (URI des Namensraums plus lokaler Name).

getAttributeNodeNS (nur DOM2)
Wie getAttributeNS, liefert aber den Attributknoten statt des Attributwerts.

getElementsByTagNamesNS (nur DOM2)
Entspricht getElementsByTagName, erhält aber als Attribut einen voll qualifizierten Namen.

hasAttribute (nur DOM2)
Ergibt wahr, wenn das Element ein Attribut mit einem gegebenen Namen besitzt.

hasAttributeNS (DOM2 only)
Wie hasAttribute, aber mit einem voll qualifizierten Namen.

removeAttributeNS (nur DOM2)
Entfernt das Attribut mit dem gegebenen voll qualifizierten Namen aus dem Element.

setAttributeNS (nur DOM2)
Setzt das Attribut mit dem gegebenen voll qualifizierten Namen auf den angegebenen Wert.

setAttributeNodeNS (nur DOM2)
Wie setAttributeNS, allerdings wird statt des neuen Attributwerts der neue Attributknoten übergeben.

Attr

Properties

name
Der Attributname.

specified
Diese Property steht auf wahr, falls das Attribut explizit im gelesenen Dokument gesetzt war bzw. durch das Programm gesetzt wurde. Falls das Attribut dagegen durch den Standardwert in einer DTD gesetzt wurde, steht die Property auf falsch.

value
Der Attributwert in Form eines Textknotens.

ownerElement (nur DOM2)
Der Elementknoten, zu dem das Attribut gehört.

Text

Methoden

splitText
Zerlegt den Textknoten in zwei aufeinanderfolgende Textknoten, die je einen Teil des ursprünglichen Textes enthalten. Der Text im ersten Knoten endet vor dem Zeichen mit der Nummer offset , dem übergebenen Argument. Der zweite Knoten enthält den verbleibenden Text. Diese Methode ist nützlich, wenn man zwischen den zwei entstehenden Knoten weitere einfügen möchte.

CDATASection

CDATASection entspricht einem Textknoten, darf allerdings Sonderzeichen wie < oder & enthalten, ohne daß diese durch Entityreferenzen maskiert werden. Die enthaltenen Zeichendaten sind über die generischen Methoden der Node-Klasse zugänglich.

ProcessingInstruction

Properties

target
Das Target der Verarbeitungsanweisung.

data
Die Daten der Verarbeitungsanweisung.

Comment

Diese Klasse repräsentiert einen Kommentar. Die enthaltenen Zeichendaten sind über die generischen Methoden der Node-Klasse zugänglich.

EntityReference

Dies ist eine Referenz auf einen Knoten der Klasse Entity. In den meisten Fällen wird der Parser Entityreferenzen auflösen und durch ihre Werte ersetzen. Wenn ein Parser aber anders konfiguriert ist, wird er statt dessen Knoten dieses Typs erzeugen. Es gibt keine Methoden, die eine explizite Auflösung erzwingen, das kann aber als Nebeneffekt anderer Aktionen geschehen.

Entity

Diese Klasse bietet Zugriff auf ein im Dokument deklariertes Entity. Die Deklaration muß im internen Bereich der DTD erfolgen.

Properties

publicId
Der öffentliche Bezeichner einer Ressource (falls es sich um ein externes Entity handelt).

systemId
Der Systembezeichner einer Ressource (falls es sich um ein externes Entity handelt).

notationName
Falls es sich um ein durch den Parser nicht auflösbares Entity handelt, enthält diese Property eine Referenz auf eine Notation.

Notation

Ein Objekt der Klasse Notation repräsentiert eine Notationsdeklaration aus dem internen Bereich der DTD.

Properties

publicId
Der öffentliche Bezeichner der Notation.

systemId
Der Systembezeichner der Notation .

  

  

<< zurück vor >>

 

 

 

Tipp der data2type-Redaktion:
Zum Thema Perl & XML bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2003 O'Reilly Verlag GmbH & Co. KG
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "Perl & XML" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

O’Reilly Verlag GmbH & Co. KG, Balthasarstraße 81, 50670 Köln, kommentar(at)oreilly.de