local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML/Element.pod

   1 =head1 NAME
   2
   3 XML::LibXML::Element - XML::LibXML Class for Element Nodes
   4
   5 =head1 SYNOPSIS
   6
   7
   8
   9   use XML::LibXML;
  10   # Only methods specific to Element nodes are listed here,
  11   # see XML::LibXML::Node manpage for other methods
  12
  13   $node = XML::LibXML::Element->new( $name );
  14   $node->setAttribute( $aname, $avalue );
  15   $node->setAttributeNS( $nsURI, $aname, $avalue );
  16   $avalue = $node->getAttribute( $aname );
  17   $avalue = $node->setAttributeNS( $nsURI, $aname );
  18   $attrnode = $node->getAttributeNode( $aname );
  19   $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
  20   $node->removeAttribute( $aname );
  21   $node->removeAttributeNS( $nsURI, $aname );
  22   $boolean = $node->hasAttribute( $aname );
  23   $boolean = $node->hasAttributeNS( $nsURI, $aname );
  24   @nodes = $node->getChildrenByTagName($tagname);
  25   @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
  26   @nodes = $node->getChildrenByLocalName($localname);
  27   @nodes = $node->getElementsByTagName($tagname);
  28   @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
  29   @nodes = $node->getElementsByLocalName($localname);
  30   $node->appendWellBalancedChunk( $chunk );
  31   $node->appendText( $PCDATA );
  32   $node->appendTextNode( $PCDATA );
  33   $node->appendTextChild( $childname , $PCDATA );
  34   $node->setNamespace( $nsURI , $nsPrefix, $activate );
  35   $node->setNamespaceDeclURI( $nsPrefix, $newURI );
  36   $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
  37
  38 =head1 METHODS
  39
  40 The class inherits from L<<<<<< XML::LibXML::Node >>>>>>. The documentation for Inherited methods is not listed here.
  41
  42 Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
  43
  44 =over 4
  45
  46 =item new
  47
  48   $node = XML::LibXML::Element->new( $name );
  49
  50 This function creates a new node unbound to any DOM.
  51
  52
  53 =item setAttribute
  54
  55   $node->setAttribute( $aname, $avalue );
  56
  57 This method sets or replaces the node's attribute C<<<<<< $aname >>>>>> to the value C<<<<<< $avalue >>>>>>
  58
  59
  60 =item setAttributeNS
  61
  62   $node->setAttributeNS( $nsURI, $aname, $avalue );
  63
  64 Namespace-aware version of C<<<<<< setAttribute >>>>>>, where C<<<<<< $nsURI >>>>>> is a namespace URI, C<<<<<< $aname >>>>>> is a qualified name, and C<<<<<< $avalue >>>>>> is the value. The namespace URI may be null (empty or undefined) in order to
  65 create an attribute which has no namespace.
  66
  67 The current implementation differs from DOM in the following aspects
  68
  69 If an attribute with the same local name and namespace URI already exists on
  70 the element, but its prefix differs from the prefix of C<<<<<< $aname >>>>>>, then this function is supposed to change the prefix (regardless of namespace
  71 declarations and possible collisions). However, the current implementation does
  72 rather the opposite. If a prefix is declared for the namespace URI in the scope
  73 of the attribute, then the already declared prefix is used, disregarding the
  74 prefix specified in C<<<<<< $aname >>>>>>. If no prefix is declared for the namespace, the function tries to declare the
  75 prefix specified in C<<<<<< $aname >>>>>> and dies if the prefix is already taken by some other namespace.
  76
  77 According to DOM Level 2 specification, this method can also be used to create
  78 or modify special attributes used for declaring XML namespaces (which belong to
  79 the namespace "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns").
  80 This should work since version 1.61, but again the implementation differs from
  81 DOM specification in the following: if a declaration of the same namespace
  82 prefix already exists on the element, then changing its value via this method
  83 automatically changes the namespace of all elements and attributes in its
  84 scope. This is because in libxml2 the namespace URI of an element is not static
  85 but is computed from a pointer to a namespace declaration attribute.
  86
  87
  88 =item getAttribute
  89
  90   $avalue = $node->getAttribute( $aname );
  91
  92 If C<<<<<< $node >>>>>> has an attribute with the name C<<<<<< $aname >>>>>>, the value of this attribute will get returned.
  93
  94
  95 =item getAttributeNS
  96
  97   $avalue = $node->setAttributeNS( $nsURI, $aname );
  98
  99 Retrieves an attribute value by local name and namespace URI.
 100
 101
 102 =item getAttributeNode
 103
 104   $attrnode = $node->getAttributeNode( $aname );
 105
 106 Retrieve an attribute node by name. If no attribute with a given name exists, C<<<<<< undef >>>>>> is returned.
 107
 108
 109 =item getAttributeNodeNS
 110
 111   $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
 112
 113 Retrieves an attribute node by local name and namespace URI. If no attribute
 114 with a given localname and namespace exists, C<<<<<< undef >>>>>> is returned.
 115
 116
 117 =item removeAttribute
 118
 119   $node->removeAttribute( $aname );
 120
 121 The method removes the attribute C<<<<<< $aname >>>>>> from the node's attribute list, if the attribute can be found.
 122
 123
 124 =item removeAttributeNS
 125
 126   $node->removeAttributeNS( $nsURI, $aname );
 127
 128 Namespace version of C<<<<<< removeAttribute >>>>>>
 129
 130
 131 =item hasAttribute
 132
 133   $boolean = $node->hasAttribute( $aname );
 134
 135 This function tests if the named attribute is set for the node. If the
 136 attribute is specified, TRUE (1) will be returned, otherwise the return value
 137 is FALSE (0).
 138
 139
 140 =item hasAttributeNS
 141
 142   $boolean = $node->hasAttributeNS( $nsURI, $aname );
 143
 144 namespace version of C<<<<<< hasAttribute >>>>>>
 145
 146
 147 =item getChildrenByTagName
 148
 149   @nodes = $node->getChildrenByTagName($tagname);
 150
 151 The function gives direct access to all child elements of the current node with
 152 a given tagname, where tagname is a qualified name, that is, in case of
 153 namespace usage it may consist of a prefix and local name. This function makes
 154 things a lot easier if one needs to handle big data sets. A special tagname '*'
 155 can be used to match any name.
 156
 157 If this function is called in SCALAR context, it returns the number of elements
 158 found.
 159
 160
 161 =item getChildrenByTagNameNS
 162
 163   @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
 164
 165 Namespace version of C<<<<<< getChildrenByTagName >>>>>>. A special nsURI '*' matches any namespace URI, in which case the function
 166 behaves just like C<<<<<< getChildrenByLocalName >>>>>>.
 167
 168 If this function is called in SCALAR context, it returns the number of elements
 169 found.
 170
 171
 172 =item getChildrenByLocalName
 173
 174   @nodes = $node->getChildrenByLocalName($localname);
 175
 176 The function gives direct access to all child elements of the current node with
 177 a given local name. It makes things a lot easier if one needs to handle big
 178 data sets. A special C<<<<<< localname >>>>>> '*' can be used to match any local name.
 179
 180 If this function is called in SCALAR context, it returns the number of elements
 181 found.
 182
 183
 184 =item getElementsByTagName
 185
 186   @nodes = $node->getElementsByTagName($tagname);
 187
 188 This function is part of the spec. It fetches all descendants of a node with a
 189 given tagname, where C<<<<<< tagname >>>>>> is a qualified name, that is, in case of namespace usage it may consist of a
 190 prefix and local name. A special C<<<<<< tagname >>>>>> '*' can be used to match any tag name.
 191
 192 In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
 193
 194
 195 =item getElementsByTagNameNS
 196
 197   @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
 198
 199 Namespace version of C<<<<<< getElementsByTagName >>>>>> as found in the DOM spec. A special C<<<<<< localname >>>>>> '*' can be used to match any local name and C<<<<<< nsURI >>>>>> '*' can be used to match any namespace URI.
 200
 201 In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
 202
 203
 204 =item getElementsByLocalName
 205
 206   @nodes = $node->getElementsByLocalName($localname);
 207
 208 This function is not found in the DOM specification. It is a mix of
 209 getElementsByTagName and getElementsByTagNameNS. It will fetch all tags
 210 matching the given local-name. This allows one to select tags with the same
 211 local name across namespace borders.
 212
 213 In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
 214
 215
 216 =item appendWellBalancedChunk
 217
 218   $node->appendWellBalancedChunk( $chunk );
 219
 220 Sometimes it is necessary to append a string coded XML Tree to a node. I<<<<<< appendWellBalancedChunk >>>>>> will do the trick for you. But this is only done if the String is C<<<<<< well-balanced >>>>>>.
 221
 222 I<<<<<< Note that appendWellBalancedChunk() is only left for compatibility reasons >>>>>>. Implicitly it uses
 223
 224
 225
 226   my $fragment = $parser->parse_xml_chunk( $chunk );
 227    $node->appendChild( $fragment );
 228
 229 This form is more explicit and makes it easier to control the flow of a script.
 230
 231
 232 =item appendText
 233
 234   $node->appendText( $PCDATA );
 235
 236 alias for appendTextNode().
 237
 238
 239 =item appendTextNode
 240
 241   $node->appendTextNode( $PCDATA );
 242
 243 This wrapper function lets you add a string directly to an element node.
 244
 245
 246 =item appendTextChild
 247
 248   $node->appendTextChild( $childname , $PCDATA );
 249
 250 Somewhat similar with C<<<<<< appendTextNode >>>>>>: It lets you set an Element, that contains only a C<<<<<< text node >>>>>> directly by specifying the name and the text content.
 251
 252
 253 =item setNamespace
 254
 255   $node->setNamespace( $nsURI , $nsPrefix, $activate );
 256
 257 setNamespace() allows one to apply a namespace to an element. The function
 258 takes three parameters: 1. the namespace URI, which is required and the two
 259 optional values prefix, which is the namespace prefix, as it should be used in
 260 child elements or attributes as well as the additional activate parameter. If
 261 prefix is not given, undefined or empty, this function tries to create a
 262 declaration of the default namespace.
 263
 264 The activate parameter is most useful: If this parameter is set to FALSE (0), a
 265 new namespace declaration is simply added to the element while the element's
 266 namespace itself is not altered. Nevertheless, activate is set to TRUE (1) on
 267 default. In this case the namespace is used as the node's effective namespace.
 268 This means the namespace prefix is added to the node name and if there was a
 269 namespace already active for the node, it will be replaced (but its declaration
 270 is not removed from the document). A new namespace declaration is only created
 271 if necessary (that is, if the element is already in the scope of a namespace
 272 declaration associating the prefix with the namespace URI, then this
 273 declaration is reused).
 274
 275 The following example may clarify this:
 276
 277
 278
 279   my $e1 = $doc->createElement("bar");
 280    $e1->setNamespace("http://foobar.org", "foo")
 281
 282 results
 283
 284
 285
 286   <foo:bar xmlns:foo="http://foobar.org"/>
 287
 288 while
 289
 290
 291
 292   my $e2 = $doc->createElement("bar");
 293    $e2->setNamespace("http://foobar.org", "foo",0)
 294
 295 results only
 296
 297
 298
 299   <bar xmlns:foo="http://foobar.org"/>
 300
 301 By using $activate == 0 it is possible to create multiple namespace
 302 declarations on a single element.
 303
 304 The function fails if it is required to create a declaration associating the
 305 prefix with the namespace URI but the element already carries a declaration
 306 with the same prefix but different namespace URI.
 307
 308
 309 =item setNamespaceDeclURI
 310
 311   $node->setNamespaceDeclURI( $nsPrefix, $newURI );
 312
 313 EXPERIMENTAL IN 1.61 !
 314
 315 This function manipulates directly with an existing namespace declaration on an
 316 element. It takes two parameters: the prefix by which it looks up the namespace
 317 declaration and a new namespace URI which replaces its previous value.
 318
 319 It returns 1 if the namespace declaration was found and changed, 0 otherwise.
 320
 321 All elements and attributes (even those previously unbound from the document)
 322 for which the namespace declaration determines their namespace belong to the
 323 new namespace after the change.
 324
 325 If the new URI is undef or empty, the nodes have no namespace and no prefix
 326 after the change. Namespace declarations once nulled in this way do not further
 327 appear in the serialized output (but do remain in the document for internal
 328 integrity of libxml2 data structures).
 329
 330 This function is NOT part of any DOM API.
 331
 332
 333 =item setNamespaceDeclPrefix
 334
 335   $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
 336
 337 EXPERIMENTAL IN 1.61 !
 338
 339 This function manipulates directly with an existing namespace declaration on an
 340 element. It takes two parameters: the old prefix by which it looks up the
 341 namespace declaration and a new prefix which is to replace the old one.
 342
 343 The function dies with an error if the element is in the scope of another
 344 declaration whose prefix equals to the new prefix, or if the change should
 345 result in a declaration with a non-empty prefix but empty namespace URI.
 346 Otherwise, it returns 1 if the namespace declaration was found and changed and
 347 0 if not found.
 348
 349 All elements and attributes (even those previously unbound from the document)
 350 for which the namespace declaration determines their namespace change their
 351 prefix to the new value.
 352
 353 If the new prefix is undef or empty, the namespace declaration becomes a
 354 declaration of a default namespace. The corresponding nodes drop their
 355 namespace prefix (but remain in the, now default, namespace). In this case the
 356 function fails, if the containing element is in the scope of another default
 357 namespace declaration.
 358
 359 This function is NOT part of any DOM API.
 360
 361
 362
 363 =back
 364
 365 =head1 AUTHORS
 366
 367 Matt Sergeant,
 368 Christian Glahn,
 369 Petr Pajas
 370
 371
 372 =head1 VERSION
 373
 374 1.70
 375
 376 =head1 COPYRIGHT
 377
 378 2001-2007, AxKit.com Ltd.
 379
 380 2002-2006, Christian Glahn.
 381
 382 2006-2009, Petr Pajas.
 383
 384 =cut