element(3)

NAME

XML::DOM::Element - An XML element node in XML::DOM

DESCRIPTION

XML::DOM::Element extends XML::DOM::Node.

By far the vast majority of objects (apart from text) that
authors encounter when traversing a document are Element
nodes. Assume the following XML document:

<elementExample id="demo">

<subelement1/>
<subelement2><subsubelement/></subelement2>

</elementExample>

When represented using DOM, the top node is an Element
node for "elementExample", which contains two child Ele
ment nodes, one for "subelement1" and one for "subele
ment2". "subelement1" contains no child nodes.

Elements may have attributes associated with them; since
the Element interface inherits from Node, the generic Node
interface method getAttributes may be used to retrieve the
set of all attributes for an element. There are methods on
the Element interface to retrieve either an Attr object by
name or an attribute value by name. In XML, where an
attribute value may contain entity references, an Attr
object should be retrieved to examine the possibly fairly
complex sub-tree representing the attribute value. On the
other hand, in HTML, where all attributes have simple
string values, methods to directly access an attribute
value can safely be used as a convenience.

METHODS

getTagName

The name of the element. For example, in:

<elementExample id="demo">

...

</elementExample>

tagName has the value "elementExample". Note that this
is case-preserving in XML, as are all of the opera
tions of the DOM.

getAttribute (name)

Retrieves an attribute value by name.

Return Value: The Attr value as a string, or the empty
string if that attribute does not have a specified or
default value.

setAttribute (name, value)

Adds a new attribute. If an attribute with that name
is already present in the element, its value is
changed to be that of the value parameter. This value
is a simple string, it is not parsed as it is being
set. So any markup (such as syntax to be recognized as
an entity reference) is treated as literal text, and
needs to be appropriately escaped by the
implementation when it is written out. In order to
assign an attribute value that contains entity refer
ences, the user must create an Attr node plus any Text
and EntityReference nodes, build the appropriate sub
tree, and use setAttributeNode to assign it as the
value of an attribute.

DOMExceptions:

· INVALID_CHARACTER_ERR

Raised if the specified name contains an invalid
character.

· NO_MODIFICATION_ALLOWED_ERR

Raised if this node is readonly.

removeAttribute (name)

Removes an attribute by name. If the removed attribute
has a default value it is immediately replaced.

DOMExceptions:

· NO_MODIFICATION_ALLOWED_ERR

Raised if this node is readonly.

getAttributeNode

Retrieves an Attr node by name.

Return Value: The Attr node with the specified
attribute name or undef if there is no such attribute.

setAttributeNode (attr)

Adds a new attribute. If an attribute with that name
is already present in the element, it is replaced by
the new one.

Return Value: If the newAttr attribute replaces an
existing attribute with the same name, the previously
existing Attr node is returned, otherwise undef is
returned.

DOMExceptions:

· WRONG_DOCUMENT_ERR

Raised if newAttr was created from a different
document than the one that created the element.

· NO_MODIFICATION_ALLOWED_ERR

Raised if this node is readonly.

· INUSE_ATTRIBUTE_ERR

Raised if newAttr is already an attribute of
another Element object. The DOM user must explic
itly clone Attr nodes to re-use them in other ele
ments.

removeAttributeNode (oldAttr)

Removes the specified attribute. If the removed Attr
has a default value it is immediately replaced. If the
Attr already is the default value, nothing happens and
nothing is returned.

Parameters:

oldAttr The Attr node to remove from the attribute

list.

Return Value: The Attr node that was removed.

DOMExceptions:

· NO_MODIFICATION_ALLOWED_ERR

Raised if this node is readonly.

· NOT_FOUND_ERR

Raised if oldAttr is not an attribute of the ele
ment.

Additional methods not in the DOM Spec

setTagName (newTagName)

Sets the tag name of the Element. Note that this
method is not portable between DOM implementa
tions.

DOMExceptions:

· INVALID_CHARACTER_ERR

Raised if the specified name contains an
invalid character.

check ($checker)

Uses the specified XML::Checker to validate the
document. NOTE: an XML::Checker must be supplied.
The checker can be created in different ways, e.g.
when parsing a document with XML::DOM::ValParser,
or with XML::DOM::Document::createChecker(). See XML::Checker for more info.

perl v5.8.0 2000-01-31 ELEMENT(1)