home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / DOM.pod < prev    next >
Encoding:
Text File  |  2003-08-22  |  5.0 KB  |  113 lines
  1. =head1 NAME
  2.  
  3. XML::LibXML::DOM - XML::LibXML DOM Implementation
  4.  
  5.  
  6. =head1 DESCRIPTION
  7.  
  8. XML::LibXML provides an lightwight interface to modify node of the document
  9. tree generated by the XML::LibXML parser. This interface follows as far as
  10. possible the DOM Level 3 specification. Additionally to the specified functions
  11. the XML::LibXML supports some functions that are more handy to use in the perl
  12. environment.
  13.  
  14. One also has to remember, that XML::LibXML is an interface to libxml2 nodes
  15. which actually reside on the C-Level of XML::LibXML. This means each node is a
  16. reference to a structure different than a perl hash or array. The only way to
  17. access these structure's values is through the DOM interface provided by
  18. XML::LibXML. This also means, that one can't simply inherit a XML::LibXML node
  19. and add new member variables as they were hash keys.
  20.  
  21. The DOM interface of XML::LibXML does not intend to implement a full DOM
  22. interface as it is done by XML::GDOME and used for full featured application.
  23. More it offers an simple way to build or modify documents that are created by
  24. XML::LibXML's parser.
  25.  
  26. Another target of the XML::LibXML interface is to make the interfaces of
  27. libxml2 available to the perl community. This includes also some workarounds to
  28. some features where libxml2 assumes more control over the C-Level that most
  29. perl users don't have.
  30.  
  31. One of the most important parts of the XML::LibXML DOM interface is, that the
  32. interfaces try do follow the DOM Level 3 specification rather strict. This
  33. means the interface functions are names as the DOM specification says and not
  34. what widespread Java interfaces claim to be standard. Although there are
  35. several functions that have only a singular interface that is conform to the
  36. DOM spec XML::LibXML provides an additional Java style alias interface.
  37.  
  38. Also there are some function interfaces left over from early stages of
  39. XML::LibXML for compatibility reasons. These interfaces are for compatibility
  40. reasons only. They might disappear in one of the future versions of
  41. XML::LibXML, so a user is requested to switch over the official functions.
  42.  
  43. More recent versions of perl (e.g. 5.6.1 or higher) support special flags to
  44. disinguish between UTF8 and so called binary data. XML::LibXML provides for
  45. these versions functionality to make efficient use of these flags: If a
  46. document has set an encoding other than UTF8 all strings that are not already
  47. in UTF8 are implicitly encoded from the document encoding to UTF8. On output
  48. these strings are commonly returned as UTF8 unless a user does request
  49. explicitly the original (aka. document) encoding.
  50.  
  51. Older version of perl (such as 5.00503 or less) do not support these flags. If
  52. XML::LibXML is build for these versions, all strings have to get encoded to
  53. UTF8 manualy before they are passed to any DOM functions.
  54.  
  55. NOTE: XML::LibXML's magic encoding may not work on all plattforms. Some
  56. platforms are known to have a broken iconv(), which is partly used by libxml2.
  57. To test if your platform works correctly with your language encoding, build a
  58. simple document in the particular encoding and try to parse it with
  59. XML::LibXML. If your document gets parsed with out causing any segmentation
  60. faults, bus errors or whatever your OS throws. An example for such a test can
  61. be found in test 19encoding.t of the distribution.
  62.  
  63. Namespaces and XML::LibXML's DOM implementation
  64.  
  65. XML::LibXML's DOM implementation follows the DOM implementation of libxml2.
  66. This is important to know if namespaces are used. Namespaces cannot be declared
  67. on an document node. This is basicly because XPath doesn't know about document
  68. nodes. Therefore namespaces have to be declared on element nodes. This can
  69. happen explicitly by using XML::LibXML:Element's setNamespace() function or
  70. more or less implicitly by using XML::LibXML::Document's createElementNS() or
  71. createAttributeNS() function. If the a namespace is not declared on the
  72. documentElement, the namespace will be localy declared for the newly created
  73. node. In case of Attributes this may look a bit confusing, since these nodes
  74. cannot have namespace declarations itself. In this case the namespace in
  75. internally applied to the attribute and later declared on the node the
  76. attribute is appended to.
  77.  
  78. The following example may explain this a bit:
  79.  
  80.    my $doc = XML::LibXML->createDocument;
  81.    my $root = $doc->createElementNS( "", "foo" );
  82.    $doc->setDocumentElement( $root );
  83.   
  84.    my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
  85.    $root->setAttributeNodeNS( $attr );               
  86.  
  87. This piece of code will result the following document:
  88.  
  89.    <?xml version="1.0"?>
  90.    <foo xmlns:bar="bar" bar:foo="test"/>
  91.  
  92. Note that the namespace is declared on the document element while the
  93. setAttributeNodeNS() call.
  94.  
  95. Here it is important to repeat the specification: While working with namespaces
  96. you should use the namespace aware functions instead of the simplified
  97. versions. For example you should never use setAttributeNode() but
  98. setAttributeNodeNS().
  99.  
  100. =head1 AUTHORS
  101.  
  102. Matt Sergeant, 
  103. Christian Glahn, 
  104. =head1 VERSION
  105.  
  106. 1.56
  107.  
  108. =head1 COPYRIGHT
  109.  
  110. 2001-2002, AxKit.com Ltd; 2001-2003 Christian Glahn, All rights reserved.
  111.  
  112. =cut
  113.