home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / Element.pod < prev    next >
Encoding:
Text File  |  2002-06-15  |  5.0 KB  |  190 lines
  1. =head1 NAME
  2.  
  3. XML::DOM::Element - An XML element node in XML::DOM
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. XML::DOM::Element extends L<XML::DOM::Node>.
  8.  
  9. By far the vast majority of objects (apart from text) that authors
  10. encounter when traversing a document are Element nodes. Assume the
  11. following XML document:
  12.  
  13.      <elementExample id="demo">
  14.        <subelement1/>
  15.        <subelement2><subsubelement/></subelement2>
  16.      </elementExample>
  17.  
  18. When represented using DOM, the top node is an Element node for
  19. "elementExample", which contains two child Element nodes, one for
  20. "subelement1" and one for "subelement2". "subelement1" contains no
  21. child nodes.
  22.  
  23. Elements may have attributes associated with them; since the Element
  24. interface inherits from Node, the generic Node interface method
  25. getAttributes may be used to retrieve the set of all attributes for an
  26. element. There are methods on the Element interface to retrieve either
  27. an Attr object by name or an attribute value by name. In XML, where an
  28. attribute value may contain entity references, an Attr object should be
  29. retrieved to examine the possibly fairly complex sub-tree representing
  30. the attribute value. On the other hand, in HTML, where all attributes
  31. have simple string values, methods to directly access an attribute
  32. value can safely be used as a convenience.
  33.  
  34. =head2 METHODS
  35.  
  36. =over 4
  37.  
  38. =item getTagName
  39.  
  40. The name of the element. For example, in:
  41.  
  42.                <elementExample id="demo">
  43.                        ...
  44.                </elementExample>
  45.  
  46. tagName has the value "elementExample". Note that this is
  47. case-preserving in XML, as are all of the operations of the
  48. DOM.
  49.  
  50. =item getAttribute (name)
  51.  
  52. Retrieves an attribute value by name.
  53.  
  54. Return Value: The Attr value as a string, or the empty string if that
  55. attribute does not have a specified or default value.
  56.  
  57. =item setAttribute (name, value)
  58.  
  59. Adds a new attribute. If an attribute with that name is
  60. already present in the element, its value is changed to be
  61. that of the value parameter. This value is a simple string,
  62. it is not parsed as it is being set. So any markup (such as
  63. syntax to be recognized as an entity reference) is treated as
  64. literal text, and needs to be appropriately escaped by the
  65. implementation when it is written out. In order to assign an
  66. attribute value that contains entity references, the user
  67. must create an Attr node plus any Text and EntityReference
  68. nodes, build the appropriate subtree, and use
  69. setAttributeNode to assign it as the value of an attribute.
  70.  
  71.  
  72. DOMExceptions:
  73.  
  74. =over 4
  75.  
  76. =item * INVALID_CHARACTER_ERR
  77.  
  78. Raised if the specified name contains an invalid character.
  79.  
  80. =item * NO_MODIFICATION_ALLOWED_ERR
  81.  
  82. Raised if this node is readonly.
  83.  
  84. =back
  85.  
  86. =item removeAttribute (name)
  87.  
  88. Removes an attribute by name. If the removed attribute has a
  89. default value it is immediately replaced.
  90.  
  91. DOMExceptions:
  92.  
  93. =over 4
  94.  
  95. =item * NO_MODIFICATION_ALLOWED_ERR
  96.  
  97. Raised if this node is readonly.
  98.  
  99. =back
  100.  
  101. =item getAttributeNode
  102.  
  103. Retrieves an Attr node by name.
  104.  
  105. Return Value: The Attr node with the specified attribute name or undef
  106. if there is no such attribute.
  107.  
  108. =item setAttributeNode (attr)
  109.  
  110. Adds a new attribute. If an attribute with that name is
  111. already present in the element, it is replaced by the new one.
  112.  
  113. Return Value: If the newAttr attribute replaces an existing attribute
  114. with the same name, the previously existing Attr node is
  115. returned, otherwise undef is returned.
  116.  
  117. DOMExceptions:
  118.  
  119. =over 4
  120.  
  121. =item * WRONG_DOCUMENT_ERR
  122.  
  123. Raised if newAttr was created from a different document than the one that created
  124. the element.
  125.  
  126. =item * NO_MODIFICATION_ALLOWED_ERR
  127.  
  128. Raised if this node is readonly.
  129.  
  130. =item * INUSE_ATTRIBUTE_ERR
  131.  
  132. Raised if newAttr is already an attribute of another Element object. The DOM
  133. user must explicitly clone Attr nodes to re-use them in other elements.
  134.  
  135. =back
  136.  
  137. =item removeAttributeNode (oldAttr)
  138.  
  139. Removes the specified attribute. If the removed Attr has a default value it is
  140. immediately replaced. If the Attr already is the default value, nothing happens
  141. and nothing is returned.
  142.  
  143. Parameters:
  144.  I<oldAttr>  The Attr node to remove from the attribute list.
  145.  
  146. Return Value: The Attr node that was removed.
  147.  
  148. DOMExceptions:
  149.  
  150. =over 4
  151.  
  152. =item * NO_MODIFICATION_ALLOWED_ERR
  153.  
  154. Raised if this node is readonly.
  155.  
  156. =item * NOT_FOUND_ERR
  157.  
  158. Raised if oldAttr is not an attribute of the element.
  159.  
  160. =back
  161.  
  162. =head2 Additional methods not in the DOM Spec
  163.  
  164. =over 4
  165.  
  166. =item setTagName (newTagName)
  167.  
  168. Sets the tag name of the Element. Note that this method is not portable
  169. between DOM implementations.
  170.  
  171. DOMExceptions:
  172.  
  173. =over 4
  174.  
  175. =item * INVALID_CHARACTER_ERR
  176.  
  177. Raised if the specified name contains an invalid character.
  178.  
  179. =back
  180.  
  181. =item check ($checker)
  182.  
  183. Uses the specified L<XML::Checker> to validate the document.
  184. NOTE: an XML::Checker must be supplied. The checker can be created in
  185. different ways, e.g. when parsing a document with XML::DOM::ValParser,
  186. or with XML::DOM::Document::createChecker().
  187. See L<XML::Checker> for more info.
  188.  
  189. =back
  190.