1<?xml version="1.0" encoding="UTF-8"?> 2<!--[ DocumentFragment object description ]--> 3<!-- $Date: 2001-06-01 07:15:37 -0400 (Fri, 01 Jun 2001) $ $Revision: 225913 $ --> 4<interface name="DocumentFragment" inherits="Node" id="ID-B63ED1A3"> 5 <descr><p><code>DocumentFragment</code> is a "lightweight" or "minimal" 6 <code>Document</code> object. It is very common to want to be able to 7 extract a portion of a document's tree or to create a new fragment of a 8 document. Imagine implementing a user command like cut or rearranging a 9 document by moving fragments around. It is desirable to have an object 10 which can hold such fragments and it is quite natural to use a Node for 11 this purpose. While it is true that a <code>Document</code> object could 12 fulfill this role, a <code>Document</code> object can potentially be a 13 heavyweight object, depending on the underlying implementation. What is 14 really needed for this is a very lightweight object. 15 <code>DocumentFragment</code> is such an object.</p> 16 <p>Furthermore, various operations -- such as inserting nodes as children 17 of another <code>Node</code> -- may take <code>DocumentFragment</code> 18 objects as arguments; this results in all the child nodes of the 19 <code>DocumentFragment</code> being moved to the child list of this 20 node.</p> 21 <p>The children of a <code>DocumentFragment</code> node are zero or more 22 nodes representing the tops of any sub-trees defining the structure of 23 the document. <code>DocumentFragment</code> nodes do not need to be 24 <termref def="dt-well-formed">well-formed XML documents</termref> (although they do need to follow the rules 25 imposed upon well-formed XML parsed entities, which can have multiple top 26 nodes). For example, a <code>DocumentFragment</code> might have only one 27 child and that child node could be a <code>Text</code> node. Such a 28 structure model represents neither an HTML document nor a well-formed XML 29 document.</p> 30 <p>When a <code>DocumentFragment</code> is inserted into a 31 <code>Document</code> (or indeed any other <code>Node</code> that may 32 take children) the children of the <code>DocumentFragment</code> and not 33 the <code>DocumentFragment</code> itself are inserted into the 34 <code>Node</code>. This makes the <code>DocumentFragment</code> very 35 useful when the user wishes to create nodes that are <termref def="dt-sibling">siblings</termref>; the 36 <code>DocumentFragment</code> acts as the parent of these nodes so that 37 the user can use the standard methods from the <code>Node</code> 38 interface, such as <code>insertBefore</code> and 39 <code>appendChild</code>.</p> 40 </descr> 41</interface> 42 43<!--[ Document object description ]--> 44<interface name="Document" inherits="Node" id="i-Document"> 45 <descr><p>The <code>Document</code> interface represents the entire 46 HTML or XML document. Conceptually, it is the <termref def="dt-root-node">root</termref> of the 47 document tree, and provides the primary access to the 48 document's data.</p> 49 <p>Since elements, text nodes, comments, processing instructions, 50 etc. cannot exist outside the context of a <code>Document</code>, the 51 <code>Document</code> interface also contains the factory methods needed 52 to create these objects. The <code>Node</code> objects created have a 53 <code>ownerDocument</code> attribute which associates them with the 54 <code>Document</code> within whose context they were created.</p> 55 </descr> 56 <attribute readonly="yes" name="doctype" type="DocumentType" 57 id="ID-B63ED1A31"> 58 <descr><p>The Document Type Declaration (see <code>DocumentType</code>) 59 associated with this document. For HTML documents as well as XML 60 documents without a document type declaration this returns 61 <code>null</code>. The DOM Level 2 does not support editing the 62 Document Type Declaration. <code>docType</code> cannot be 63 altered in any way, including through the use of methods inherited from 64 the <code>Node</code> interface, such as <code>insertNode</code> or 65 <code>removeNode</code>.</p> 66 </descr> 67 </attribute> 68 <attribute readonly="yes" name="implementation" type="DOMImplementation" 69 id="ID-1B793EBA"> 70 <descr><p>The <code>DOMImplementation</code> object that handles this 71 document. A DOM application may use objects from multiple 72 implementations.</p> 73 </descr> 74 </attribute> 75 76 <attribute readonly="yes" name="documentElement" type="Element" 77 id="ID-87CD092"> 78 <descr><p>This is a <termref def="dt-convenience">convenience</termref> attribute that allows direct 79 access to the child node that is the root element of the 80 document. For HTML documents, this is the element with 81 the tagName "HTML".</p></descr> 82 </attribute> 83 <!-- ********** --> 84 <method name="createElement" id="ID-2141741547"> 85 <descr><p>Creates an element of the type specified. Note that the instance 86 returned implements the <code>Element</code> interface, so attributes 87 can be specified directly on the returned object.</p> 88 <p>In addition, if there are known attributes with default values, 89 <code>Attr</code> nodes representing them are automatically created and 90 attached to the element.</p> 91 <p>To create an element with a qualified name and namespace URI, use the 92 <code>createElementNS</code> method.</p> 93 </descr> 94 <parameters> 95 <param name="tagName" type="DOMString" attr="in"> 96 <descr><p>The name of the element type to 97 instantiate. For XML, this is case-sensitive. For HTML, the 98 <code>tagName</code> parameter may be provided in any case, 99 but it must be mapped to the canonical uppercase form by 100 the DOM implementation. 101 </p></descr> 102 </param> 103 </parameters> 104 <returns type="Element"> 105 <descr><p>A new <code>Element</code> object with the 106 <code>nodeName</code> attribute set to <code>tagName</code>, and 107 <code>localName</code>, <code>prefix</code>, and 108 <code>namespaceURI</code> set to <code>null</code>.</p></descr> 109 </returns> 110 <raises> 111 <exception name="DOMException"> 112 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains 113 an illegal character.</p></descr> 114 </exception> 115 </raises> 116 </method> 117 118 <!-- ********** --> 119 <method name="createDocumentFragment" id="ID-35CB04B5"> 120 <descr><p>Creates an empty <code>DocumentFragment</code> object. 121 </p></descr> 122 <parameters> 123 <!-- No parameters --> 124 </parameters> 125 <returns type="DocumentFragment"> 126 <descr><p>A new <code>DocumentFragment</code>.</p></descr> 127 </returns> 128 <raises> 129 <!-- Throws no exceptions --> 130 </raises> 131 </method> 132 133 <!-- ********** --> 134 <method name="createTextNode" id="ID-1975348127"> 135 <descr><p>Creates a <code>Text</code> node given the specified 136 string.</p></descr> 137 <parameters> 138 <param name="data" type="DOMString" attr="in"> 139 <descr><p>The data for the node.</p></descr> 140 </param> 141 </parameters> 142 <returns type="Text"> 143 <descr><p>The new <code>Text</code> object.</p></descr> 144 </returns> 145 <raises> 146 <!-- Throws no exceptions --> 147 </raises> 148 </method> 149 <!-- ********** --> 150 <method name="createComment" id="ID-1334481328"> 151 <descr><p>Creates a <code>Comment</code> node given the specified 152 string.</p></descr> 153 <parameters> 154 <param name="data" type="DOMString" attr="in"> 155 <descr><p>The data for the node.</p></descr> 156 </param> 157 </parameters> 158 <returns type="Comment"> 159 <descr><p>The new <code>Comment</code> object.</p></descr> 160 </returns> 161 <raises> 162 <!-- Throws no exceptions --> 163 </raises> 164 </method> 165 <!-- ********** --> 166 <method name="createCDATASection" id="ID-D26C0AF8"> 167 <descr><p>Creates a <code>CDATASection</code> node whose value is 168 the specified string.</p></descr> 169 <parameters> 170 <param name="data" type="DOMString" attr="in"> 171 <descr><p>The data for the <code>CDATASection</code> contents.</p> 172 </descr> 173 </param> 174 </parameters> 175 <returns type="CDATASection"> 176 <descr><p>The new <code>CDATASection</code> object.</p></descr> 177 </returns> 178 <raises> 179 <exception name="DOMException"> 180 <descr><p>NOT_SUPPORTED_ERR: Raised if this document is an HTML 181 document.</p></descr> 182 </exception> 183 </raises> 184 </method> 185 <!-- ********** --> 186 <method name="createProcessingInstruction" id="ID-135944439"> 187 <descr><p>Creates a <code>ProcessingInstruction</code> node given 188 the specified name and data strings.</p></descr> 189 <parameters> 190 <param name="target" type="DOMString" attr="in"> 191 <descr><p>The target part of the processing instruction.</p></descr> 192 </param> 193 <param name="data" type="DOMString" attr="in"> 194 <descr><p>The data for the node.</p></descr> 195 </param> 196 </parameters> 197 <returns type="ProcessingInstruction"> 198 <descr><p>The new <code>ProcessingInstruction</code> object.</p></descr> 199 </returns> 200 <raises> 201 <exception name="DOMException"> 202 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified target 203 contains an illegal character.</p> 204 <p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p> 205 </descr> 206 </exception> 207 </raises> 208 </method> 209 <!-- ********** --> 210 <method name="createAttribute" id="ID-1084891198"> 211 <descr><p>Creates an <code>Attr</code> of the given name. 212 Note that the <code>Attr</code> instance 213 can then be set on an <code>Element</code> using the 214 <code>setAttributeNode</code> method. </p> 215 <p>To create an attribute with a qualified name and namespace URI, use 216 the <code>createAttributeNS</code> method.</p> 217 </descr> 218 <parameters> 219 <param name="name" type="DOMString" attr="in"> 220 <descr><p>The name of the attribute.</p></descr> 221 </param> 222 </parameters> 223 <returns type="Attr"> 224 <descr><p>A new <code>Attr</code> object with the <code>nodeName</code> 225 attribute set to <code>name</code>, and <code>localName</code>, 226 <code>prefix</code>, and <code>namespaceURI</code> set to 227 <code>null</code>. The value of the attribute is the empty 228 string.</p></descr> 229 </returns> 230 <raises> 231 <exception name="DOMException"> 232 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains 233 an illegal character.</p></descr> 234 </exception> 235 </raises> 236 </method> 237 238 239 <method name="createEntityReference" id="ID-392B75AE"> 240 <descr><p>Creates an <code>EntityReference</code> object. In addition, if 241 the referenced entity is known, the child list of the 242 <code>EntityReference</code> node is made the same as that of the 243 corresponding <code>Entity</code> node.</p> 244 <note><p>If any descendant of the <code>Entity</code> node has an 245 unbound <termref def='dt-namespaceprefix'>namespace prefix</termref>, 246 the corresponding descendant of the created 247 <code>EntityReference</code> node is also unbound; (its 248 <code>namespaceURI</code> is <code>null</code>). The DOM Level 2 does 249 not support any mechanism to resolve namespace prefixes.</p></note> 250 </descr> 251 <parameters> 252 <param name="name" type="DOMString" attr="in"> 253 <descr><p>The name of the entity to reference. </p> 254 </descr> 255 </param> 256 </parameters> 257 <returns type="EntityReference"> 258 <descr><p>The new <code>EntityReference</code> object.</p></descr> 259 </returns> 260 <raises> 261 <exception name="DOMException"> 262 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains 263 an illegal character.</p> 264 <p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p> 265 </descr> 266 </exception> 267 </raises> 268 </method> 269 270 <!-- ********** --> 271 <method name="getElementsByTagName" id="ID-A6C9094"> 272 <descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code> 273 with a given tag name in the order in which they are encountered 274 in a preorder traversal of the <code>Document</code> tree. 275 </p></descr> 276 <parameters> 277 <param name="tagname" type="DOMString" attr="in"> 278 <descr><p>The name of the tag to match on. The special value "*" 279 matches all tags.</p></descr> 280 </param> 281 </parameters> 282 <returns type="NodeList"> 283 <descr><p>A new <code>NodeList</code> object containing 284 all the matched <code>Elements</code>.</p></descr> 285 </returns> 286 <raises> 287 <!-- Throws no exceptions --> 288 </raises> 289 </method> 290 291 <!-- ****** DOM Level 2 additions ****** --> 292 <method name="importNode" id="Core-Document-importNode" since="DOM Level 2"> 293 <descr> 294 <p>Imports a node from another document to this document. The returned 295 node has no parent; (<code>parentNode</code> is <code>null</code>). The 296 source node is not altered or removed from the original document; this 297 method creates a new copy of the source node.</p> 298 299 <p>For all nodes, importing a node creates a node object owned by the 300 importing document, with attribute values identical to the source 301 node's <code>nodeName</code> and <code>nodeType</code>, plus the 302 attributes related to namespaces (<code>prefix</code>, 303 <code>localName</code>, and <code>namespaceURI</code>). As in the 304 <code>cloneNode</code> operation on a <code>Node</code>, the source 305 node is not altered.</p> 306 307 <p>Additional information is copied as appropriate to the 308 <code>nodeType</code>, attempting to mirror the behavior expected if a 309 fragment of XML or HTML source was copied from one document to another, 310 recognizing that the two documents may have different DTDs in the XML 311 case. The following list describes the specifics for each type of 312 node. 313 314 <glist> 315 <gitem> 316 <label>ATTRIBUTE_NODE</label> 317 318 <def><p>The <code>ownerElement</code> attribute is set to 319 <code>null</code> and the <code>specified</code> flag is set to 320 <code>true</code> on the generated <code>Attr</code>. The 321 <termref def="dt-descendant">descendants</termref> of the source <code>Attr</code> are recursively 322 imported and the resulting nodes reassembled to form the 323 corresponding subtree.</p> 324 <p>Note that the <code>deep</code> parameter has no effect on 325 <code>Attr</code> nodes; they always carry their children with 326 them when imported.</p> 327 </def> 328 </gitem> 329 <gitem> 330 <label>DOCUMENT_FRAGMENT_NODE</label> 331 <def><p>If the <code>deep</code> option was set to 332 <code>true</code>, the <termref def="dt-descendant">descendants</termref> of the source element are 333 recursively imported and the resulting nodes reassembled to 334 form the corresponding subtree. Otherwise, this simply 335 generates an empty <code>DocumentFragment</code>.</p> 336 </def> 337 </gitem> 338 <gitem> 339 <label>DOCUMENT_NODE</label> 340 <def><p><code>Document</code> nodes cannot be imported.</p> 341 </def> 342 </gitem> 343 <gitem> 344 <label>DOCUMENT_TYPE_NODE</label> 345 <def><p><code>DocumentType</code> nodes cannot be imported.</p> 346 </def> 347 </gitem> 348 <gitem> 349 <label>ELEMENT_NODE</label> 350 <def><p><emph>Specified</emph> attribute nodes of the source 351 element are imported, and the generated <code>Attr</code> nodes 352 are attached to the generated <code>Element</code>. Default 353 attributes are <emph>not</emph> copied, though if the document 354 being imported into defines default attributes for this element 355 name, those are assigned. If the <code>importNode</code> 356 <code>deep</code> parameter was set to <code>true</code>, the 357 <termref def="dt-descendant">descendants</termref> of the source element are recursively imported 358 and the resulting nodes reassembled to form the corresponding 359 subtree.</p> 360 </def> 361 </gitem> 362 <gitem> 363 <label>ENTITY_NODE</label> 364 <def><p><code>Entity</code> nodes can be imported, however in the 365 current release of the DOM the <code>DocumentType</code> is 366 readonly. Ability to add these imported nodes to a 367 <code>DocumentType</code> will be considered for addition to a 368 future release of the DOM.</p> 369 <p>On import, the <code>publicId</code>, <code>systemId</code>, 370 and <code>notationName</code> attributes are copied. If a 371 <code>deep</code> import is requested, the <termref def="dt-descendant">descendants</termref> of the 372 the source <code>Entity</code> are recursively imported and the 373 resulting nodes reassembled to form the corresponding 374 subtree.</p> 375 </def> 376 </gitem> 377 <gitem> 378 <label>ENTITY_REFERENCE_NODE</label> 379 <def><p>Only the <code>EntityReference</code> itself is copied, 380 even if a <code>deep</code> import is requested, since the 381 source and destination documents might have defined the entity 382 differently. If the document being imported into provides a 383 definition for this entity name, its value is assigned.</p> 384 </def> 385 </gitem> 386 <gitem> 387 <label>NOTATION_NODE</label> 388 <def><p><code>Notation</code> nodes can be imported, however in the 389 current release of the DOM the <code>DocumentType</code> is 390 readonly. Ability to add these imported nodes to a 391 <code>DocumentType</code> will be considered for addition to a 392 future release of the DOM.</p> 393 <p>On import, the <code>publicId</code> and 394 <code>systemId</code> attributes are copied.</p> 395 <p>Note that the <code>deep</code> parameter has no effect on 396 <code>Notation</code> nodes since they never have any 397 children.</p> 398 </def> 399 </gitem> 400 <gitem> 401 <label>PROCESSING_INSTRUCTION_NODE</label> 402 <def><p>The imported node copies its <code>target</code> and 403 <code>data</code> values from those of the source node.</p> 404 </def> 405 </gitem> 406 <gitem> 407 <label>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</label> 408 <def><p>These three types of nodes inheriting from 409 <code>CharacterData</code> copy their <code>data</code> and 410 <code>length</code> attributes from those of the source 411 node.</p> 412 </def> 413 </gitem> 414 </glist> 415 </p> 416 </descr> 417 <parameters> 418 <param name="importedNode" type="Node" attr="in"> 419 <descr><p>The node to import.</p></descr> 420 </param> 421 <param name="deep" type="boolean" attr="in"> 422 <descr><p>If <code>true</code>, recursively import the subtree 423 under the specified node; if <code>false</code>, import only 424 the node itself, as explained above. This has no effect on 425 <code>Attr</code>, <code>EntityReference</code>, and 426 <code>Notation</code> nodes.</p> 427 </descr> 428 </param> 429 </parameters> 430 <returns type="Node"> 431 <descr><p>The imported node that belongs to this 432 <code>Document</code>.</p></descr> 433 </returns> 434 <raises> 435 <exception name="DOMException"> 436 <descr><p>NOT_SUPPORTED_ERR: Raised if the type of node being imported 437 is not supported.</p></descr> 438 </exception> 439 </raises> 440 </method> 441 442 <method name="createElementNS" id="ID-DocCrElNS" since="DOM Level 2"> 443 <descr><p>Creates an element of the given qualified name and namespace 444 URI. HTML-only DOM implementations do not need to implement this 445 method.</p> 446 </descr> 447 <parameters> 448 <param name="namespaceURI" type="DOMString" attr="in"> 449 <descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of 450 the element to create.</p> 451 </descr> 452 </param> 453 <param name="qualifiedName" type="DOMString" attr="in"> 454 <descr><p>The <termref def='dt-qualifiedname'>qualified name</termref> 455 of the element type to instantiate.</p> 456 </descr> 457 </param> 458 </parameters> 459 <returns type="Element"> 460 <descr><p>A new <code>Element</code> object with the following 461 attributes:</p> 462 <table summary='Layout table: the first cell the name property, 463 the second cell contains his initial value'> 464 <tbody> 465 <tr><th>Attribute</th><th>Value</th></tr> 466 <tr><td><code>Node.nodeName</code></td> 467 <td><code>qualifiedName</code></td> 468 </tr> 469 <tr><td><code>Node.namespaceURI</code></td> 470 <td><code>namespaceURI</code></td></tr> 471 <tr><td><code>Node.prefix</code></td><td>prefix, extracted from 472 <code>qualifiedName</code>, or <code>null</code> if there is no 473 prefix</td></tr> 474 <tr><td><code>Node.localName</code></td><td><termref 475 def='dt-localname'>local name</termref>, extracted from 476 <code>qualifiedName</code></td></tr> 477 <tr><td><code>Element.tagName</code></td> 478 <td><code>qualifiedName</code></td> 479 </tr> 480 </tbody> 481 </table> 482 </descr> 483 </returns> 484 <raises> 485 <exception name="DOMException"> 486 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name 487 contains an illegal character.</p> 488 <p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is 489 malformed, if the <code>qualifiedName</code> has a prefix and 490 the <code>namespaceURI</code> is <code>null</code>, or if 491 the <code>qualifiedName</code> has a prefix that 492 is "xml" and the <code>namespaceURI</code> is different 493 from "<loc href='&xml-ns;'>&xml-ns;</loc>" <bibref 494 ref='Namespaces'/>.</p> 495 </descr> 496 </exception> 497 </raises> 498 </method> 499 <method name="createAttributeNS" id="ID-DocCrAttrNS" since="DOM Level 2"> 500 <descr><p>Creates an attribute of the given qualified name and namespace 501 URI. HTML-only DOM implementations do not need to implement this 502 method.</p> 503 </descr> 504 <parameters> 505 <param name="namespaceURI" type="DOMString" attr="in"> 506 <descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of 507 the attribute to create.</p> 508 </descr> 509 </param> 510 <param name="qualifiedName" type="DOMString" attr="in"> 511 <descr><p>The <termref def='dt-qualifiedname'>qualified name</termref> 512 of the attribute to instantiate.</p> 513 </descr> 514 </param> 515 </parameters> 516 <returns type="Attr"> 517 <descr><p>A new <code>Attr</code> object with the following 518 attributes:</p> 519 <table summary='Layout table: the first cell the name property, 520 the second cell contains his initial value'> 521 <tbody> 522 <tr><th>Attribute</th><th>Value</th></tr> 523 <tr><td><code>Node.nodeName</code></td><td>qualifiedName</td> 524 </tr> 525 <tr><td><code>Node.namespaceURI</code></td> 526 <td><code>namespaceURI</code></td></tr> 527 <tr><td><code>Node.prefix</code></td><td>prefix, extracted from 528 <code>qualifiedName</code>, or <code>null</code> if there is no 529 prefix</td></tr> 530 <tr><td><code>Node.localName</code></td><td><termref 531 def='dt-localname'>local name</termref>, extracted from 532 <code>qualifiedName</code></td></tr> 533 <tr><td><code>Attr.name</code></td> 534 <td><code>qualifiedName</code></td></tr> 535 <tr><td><code>Node.nodeValue</code></td> 536 <td>the empty string</td></tr> 537 </tbody> 538 </table> 539 </descr> 540 </returns> 541 <raises> 542 <exception name="DOMException"> 543 <descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name 544 contains an illegal character.</p> 545 <p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is 546 malformed, if the <code>qualifiedName</code> has a prefix and 547 the <code>namespaceURI</code> is <code>null</code>, if the 548 <code>qualifiedName</code> has a prefix that is 549 "xml" and the <code>namespaceURI</code> is different from 550 "<loc href='&xml-ns;'>&xml-ns;</loc>", or if the 551 <code>qualifiedName</code> is "xmlns" and the 552 <code>namespaceURI</code> is different from 553 "<loc href='&xmlns-ns;'>&xmlns-ns;</loc>".</p> 554 </descr> 555 </exception> 556 </raises> 557 </method> 558 <method name="getElementsByTagNameNS" id="ID-getElBTNNS" since="DOM Level 2"> 559 <descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code> 560 with a given <termref def='dt-localname'>local name</termref> and 561 namespace URI in the order in which they are encountered in a 562 preorder traversal of the <code>Document</code> tree.</p> 563 </descr> 564 <parameters> 565 <param name="namespaceURI" type="DOMString" attr="in"> 566 <descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of 567 the elements to match on. The special value "*" matches all 568 namespaces.</p> 569 </descr> 570 </param> 571 <param name="localName" type="DOMString" attr="in"> 572 <descr><p>The <termref def='dt-localname'>local name</termref> of the 573 elements to match on. The special value "*" matches all local 574 names.</p> 575 </descr> 576 </param> 577 </parameters> 578 <returns type="NodeList"> 579 <descr><p>A new <code>NodeList</code> object containing all the matched 580 <code>Elements</code>.</p></descr> 581 </returns> 582 <raises> 583 <!-- Throws no exceptions --> 584 </raises> 585 </method> 586 <method name="getElementById" id="ID-getElBId" since="DOM Level 2"> 587 <descr><p>Returns the <code>Element</code> whose <code>ID</code> 588 is given by <code>elementId</code>. If no such element exists, returns 589 <code>null</code>. Behavior is not defined if more than one element has 590 this <code>ID</code>. 591 <note><p>The DOM implementation must have information that says which 592 attributes are of type ID. Attributes with the name "ID" are not of type ID unless 593 so defined. Implementations that do not know whether attributes are of type 594 ID or not are expected to return <code>null</code>.</p></note></p></descr> 595 <parameters> 596 <param name="elementId" type="DOMString" attr="in"> 597 <descr><p>The unique <code>id</code> value for an element.</p></descr> 598 </param> 599 </parameters> 600 <returns type="Element"> 601 <descr><p>The matching element.</p></descr> 602 </returns> 603 <raises> 604 <!-- Throws no exceptions --> 605 </raises> 606 </method> 607</interface> 608