diff -r 8b87ea768cb8 -r 60053dab7e2a dummy_foundation/lib/XML/DOM/Element.pod --- a/dummy_foundation/lib/XML/DOM/Element.pod Wed Jun 03 18:33:51 2009 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,189 +0,0 @@ -=head1 NAME - -XML::DOM::Element - An XML element node in XML::DOM - -=head1 DESCRIPTION - -XML::DOM::Element extends L. - -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: - - - - - - -When represented using DOM, the top node is an Element node for -"elementExample", which contains two child Element nodes, one for -"subelement1" and one for "subelement2". "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. - -=head2 METHODS - -=over 4 - -=item getTagName - -The name of the element. For example, in: - - - ... - - -tagName has the value "elementExample". Note that this is -case-preserving in XML, as are all of the operations of the -DOM. - -=item 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. - -=item 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 references, the user -must create an Attr node plus any Text and EntityReference -nodes, build the appropriate subtree, and use -setAttributeNode to assign it as the value of an attribute. - - -DOMExceptions: - -=over 4 - -=item * INVALID_CHARACTER_ERR - -Raised if the specified name contains an invalid character. - -=item * NO_MODIFICATION_ALLOWED_ERR - -Raised if this node is readonly. - -=back - -=item removeAttribute (name) - -Removes an attribute by name. If the removed attribute has a -default value it is immediately replaced. - -DOMExceptions: - -=over 4 - -=item * NO_MODIFICATION_ALLOWED_ERR - -Raised if this node is readonly. - -=back - -=item 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. - -=item 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: - -=over 4 - -=item * WRONG_DOCUMENT_ERR - -Raised if newAttr was created from a different document than the one that created -the element. - -=item * NO_MODIFICATION_ALLOWED_ERR - -Raised if this node is readonly. - -=item * INUSE_ATTRIBUTE_ERR - -Raised if newAttr is already an attribute of another Element object. The DOM -user must explicitly clone Attr nodes to re-use them in other elements. - -=back - -=item 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: - I The Attr node to remove from the attribute list. - -Return Value: The Attr node that was removed. - -DOMExceptions: - -=over 4 - -=item * NO_MODIFICATION_ALLOWED_ERR - -Raised if this node is readonly. - -=item * NOT_FOUND_ERR - -Raised if oldAttr is not an attribute of the element. - -=back - -=head2 Additional methods not in the DOM Spec - -=over 4 - -=item setTagName (newTagName) - -Sets the tag name of the Element. Note that this method is not portable -between DOM implementations. - -DOMExceptions: - -=over 4 - -=item * INVALID_CHARACTER_ERR - -Raised if the specified name contains an invalid character. - -=back - -=item check ($checker) - -Uses the specified L 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 L for more info. - -=back