Location: PHPKode > scripts > ParamsProxy > paramsproxy-1-5a/assets/domit/documentation/xml_domit_parser_docs.html
<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>The DOMIT! XML Parser Manual</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e1"></a>The DOMIT! XML Parser Manual</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#d0e4">1. Overview of XML</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e7">1. Intro to XML</a></span></dt><dt><span class="section"><a href="#d0e27">2. Types of XML Content</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e32">2.1. XML Elements</a></span></dt><dt><span class="section"><a href="#d0e119">2.2. XML Attributes</a></span></dt><dt><span class="section"><a href="#d0e162">2.3. Character Data</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e175">2.3.1. Illegal Characters</a></span></dt><dt><span class="section"><a href="#d0e233">2.3.2. CDATA Sections</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e283">2.4. Comments</a></span></dt><dt><span class="section"><a href="#d0e306">2.5. Processing Instructions</a></span></dt><dt><span class="section"><a href="#d0e359">2.6. Document Type Declarations</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e377">2. Overview of the DOM</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e380">1. Intro to the DOM</a></span></dt><dt><span class="section"><a href="#d0e408">2. Types of DOM Nodes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e429">2.1. Document Nodes</a></span></dt><dt><span class="section"><a href="#d0e453">2.2. Element Nodes</a></span></dt><dt><span class="section"><a href="#d0e484">2.3. Attribute Nodes</a></span></dt><dt><span class="section"><a href="#d0e515">2.4. Text Nodes</a></span></dt><dt><span class="section"><a href="#d0e546">2.5. CDATA Section Nodes</a></span></dt><dt><span class="section"><a href="#d0e574">2.6. Comment Nodes</a></span></dt><dt><span class="section"><a href="#d0e602">2.7. Processing Instruction Nodes</a></span></dt><dt><span class="section"><a href="#d0e630">2.8. Document Type Declarations</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e640">3. The Structure of a DOM Document</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e649">3.1. Child Nodes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e740">3.1.1. First Child</a></span></dt><dt><span class="section"><a href="#d0e767">3.1.2. Last Child</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e794">3.2. Parent Nodes</a></span></dt><dt><span class="section"><a href="#d0e856">3.3. Sibling Nodes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e866">3.3.1. Previous Sibling</a></span></dt><dt><span class="section"><a href="#d0e903">3.3.2. Next Sibling</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e934">3.4. Attribute Nodes</a></span></dt><dt><span class="section"><a href="#d0e955">3.5. Owner Document</a></span></dt><dt><span class="section"><a href="#d0e963">3.6. Document Element</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e976">3. Installing DOMIT</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e979">1. What is DOMIT!?</a></span></dt><dt><span class="section"><a href="#d0e1017">2. Installing DOMIT!</a></span></dt><dt><span class="section"><a href="#d0e1111">3. Installing DOMIT! Lite</a></span></dt><dt><span class="section"><a href="#d0e1192">4. Including the DOMIT! Library in your Scripts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d0e1211">4. Loading a DOMIT_Document</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1214">1. Instantiating and Populating a DOMIT_Document</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1219">1.1. Instantiating a DOMIT_Document</a></span></dt><dt><span class="section"><a href="#d0e1236">1.2. <code class="function">parseXML</code>: Populating a DOMIT_Document from a string variable</a></span></dt><dt><span class="section"><a href="#d0e1256">1.3. <code class="function">loadXML</code>: Populating a DOMIT_Document from a file or url</a></span></dt><dt><span class="section"><a href="#d0e1278">1.4. <code class="function">useSAXY</code>: Specifiying a SAX parser</a></span></dt><dt><span class="section"><a href="#d0e1318">1.5. Determining the base SAX parser</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e1336">2. Optional Settings for Loading XML Data</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1348">2.1. <code class="function">useHTTPClient:</code> Forcing loadXML to use an HTTP Client</a></span></dt><dt><span class="section"><a href="#d0e1368">2.2. <code class="function">setConnection</code>: Manually specifying HTTP connection parameters</a></span></dt><dt><span class="section"><a href="#d0e1398">2.3. <code class="function">setAuthorization</code>: Using basic HTTP authorization with your connection</a></span></dt><dt><span class="section"><a href="#d0e1421">2.4. <code class="function">setProxyConnection</code>: Retrieving XML data through a proxy server</a></span></dt><dt><span class="section"><a href="#d0e1444">2.5. <code class="function">setProxyAuthorization</code>: Using basic HTTP authorization with your proxy</a></span></dt><dt><span class="section"><a href="#d0e1459">2.6. <code class="function">preserveWhiteSpace</code></a></span></dt><dt><span class="section"><a href="#d0e1470">2.7. <code class="function">appendEntityTranslationTable</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e1495">3. Error Handling During and After Loading an XML Document</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1502">3.1. <code class="function">resolveErrors</code></a></span></dt><dt><span class="section"><a href="#d0e1528">3.2. <code class="function">getErrorCode</code> and <code class="function">getErrorString</code></a></span></dt><dt><span class="section"><a href="#d0e1559">3.3. DOMIT_DOMException::setErrorHandler</a></span></dt><dt><span class="section"><a href="#d0e1606">3.4. <code class="function">DOMIT_DOMException::setErrorMode</code></a></span></dt><dt><span class="section"><a href="#d0e1631">3.5. <code class="function">DOMIT_DOMException::setErrorLog</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e1654">5. Traversing a Document and Extracting Data</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1659">1. The Document Element Node</a></span></dt><dt><span class="section"><a href="#d0e1677">2. Displaying a Node as Text</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1693">2.1. <code class="function">toString</code></a></span></dt><dt><span class="section"><a href="#d0e1733">2.2. <code class="function">toNormalizedString</code></a></span></dt><dt><span class="section"><a href="#d0e1762">2.3. expandEmptyElementTags</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e1798">3. Obtaining Node Type, Name, and Value</a></span></dt><dt><span class="section"><a href="#d0e1829">4. Traversing a DOM Tree</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e1858">4.1. The <code class="computeroutput"><code class="function">childNodes</code></code> array, <code class="computeroutput"><code class="function">hasChildNodes</code></code>, and <code class="computeroutput"><code class="function">childCount</code></code></a></span></dt><dt><span class="section"><a href="#d0e1918">4.2. <code class="computeroutput"><code class="function">firstChild</code></code></a></span></dt><dt><span class="section"><a href="#d0e1950">4.3. <code class="function">lastChild</code></a></span></dt><dt><span class="section"><a href="#d0e1974">4.4. <code class="function">nextSibling</code></a></span></dt><dt><span class="section"><a href="#d0e2012">4.5. <code class="function">previousSibling</code></a></span></dt><dt><span class="section"><a href="#d0e2045">4.6. <code class="function">parentNode</code></a></span></dt><dt><span class="section"><a href="#d0e2078">4.7. <code class="function">ownerDocument</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2092">5. Extracting Character Data</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2097">5.1. nodeValue</a></span></dt><dt><span class="section"><a href="#d0e2124">5.2. getData</a></span></dt><dt><span class="section"><a href="#d0e2138">5.3. getText</a></span></dt><dt><span class="section"><a href="#d0e2177">5.4. getLength</a></span></dt><dt><span class="section"><a href="#d0e2188">5.5. substringData</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2211">6. Accessing Attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2222">6.1. <code class="function">hasAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e2240">6.2. <code class="function">hasAttributes</code></a></span></dt><dt><span class="section"><a href="#d0e2252">6.3. <code class="function">getAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e2275">6.4. <code class="function">getAttributeNode</code> and <code class="function">getValue</code></a></span></dt><dt><span class="section"><a href="#d0e2305">6.5. The <code class="function">attributes</code> Keyword and Named Node Maps</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2318">6.5.1. The <code class="function">attributes</code> Keyword</a></span></dt><dt><span class="section"><a href="#d0e2332">6.5.2. getLength, item, and getName</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#d0e2361">7. Accessing the XML Prolog</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2369">7.1. <code class="function">getXMLDeclaration</code></a></span></dt><dt><span class="section"><a href="#d0e2383">7.2. Accessing the Document Type Declaration</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e2395">6. Creating and Modifying a DOM Document</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2400">1. Creating Nodes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2408">1.1. <code class="function">createElement</code></a></span></dt><dt><span class="section"><a href="#d0e2427">1.2. <code class="function">createTextNode</code></a></span></dt><dt><span class="section"><a href="#d0e2444">1.3. <code class="function">createCDATASection</code></a></span></dt><dt><span class="section"><a href="#d0e2461">1.4. <code class="function">createAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e2485">1.5. <code class="function">createComment</code></a></span></dt><dt><span class="section"><a href="#d0e2502">1.6. <code class="function">createProcessingInstruction</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2519">2. Appending Nodes</a></span></dt><dt><span class="section"><a href="#d0e2542">3. Setting the Document Element</a></span></dt><dt><span class="section"><a href="#d0e2564">4. Setting Attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2575">4.1. <code class="function">setAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e2607">4.2. <code class="function">setAttributeNode</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2624">5. Creating the cdlibrary XML Using DOMIT!</a></span></dt><dt><span class="section"><a href="#d0e2637">6. Inserting Nodes</a></span></dt><dt><span class="section"><a href="#d0e2672">7. Replacing Nodes</a></span></dt><dt><span class="section"><a href="#d0e2697">8. Removing Nodes</a></span></dt><dt><span class="section"><a href="#d0e2714">9. Removing Attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2725">9.1. <code class="function">removeAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e2749">9.2. <code class="function">removeAttributeNode</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2773">10. Setting Character Data</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2778">10.1. <code class="function">setText</code></a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2797">10.1.1. <code class="function">setText</code> When Called from an Element</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e2831">10.2. <code class="function">splitText</code></a></span></dt><dt><span class="section"><a href="#d0e2852">10.3. <code class="function">normalize</code></a></span></dt><dt><span class="section"><a href="#d0e2884">10.4. <code class="function">appendData</code></a></span></dt><dt><span class="section"><a href="#d0e2901">10.5. <code class="function">insertData</code></a></span></dt><dt><span class="section"><a href="#d0e2920">10.6. <code class="function">replaceData</code></a></span></dt><dt><span class="section"><a href="#d0e2939">10.7. <code class="function">deleteData</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e2958">7. Saving a DOM Document</a></span></dt><dt><span class="chapter"><a href="#d0e2983">8. Miscellaneous DOM Features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e2988">1. <code class="function">cloneNode</code></a></span></dt><dt><span class="section"><a href="#d0e3019">2. <code class="function">getElementByID</code></a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3077">2.1. <code class="function">getElementByID</code> and Strict vs. Tolerant mode</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3114">3. <code class="function">getElementsByTagName</code></a></span></dt><dt><span class="section"><a href="#d0e3148">4. Using NodeLists</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3164">4.1. <code class="function">getLength</code> and <code class="function">item</code></a></span></dt><dt><span class="section"><a href="#d0e3195">4.2. <code class="function">appendNode</code> and <code class="function">removeNode</code></a></span></dt><dt><span class="section"><a href="#d0e3236">4.3. childNodesAsNodeList</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3261">5. <code class="function">importNode</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="#d0e3306">9. Custom DOMIT! Methods</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3311">1. <code class="function">getVersion</code></a></span></dt><dt><span class="section"><a href="#d0e3323">2. Searching for Nodes</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3334">2.1. <code class="function">getElementsByPath</code></a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3396">2.1.1. Absolute Path Search</a></span></dt><dt><span class="section"><a href="#d0e3417">2.1.2. Relative Path Search</a></span></dt><dt><span class="section"><a href="#d0e3444">2.1.3. Variable Path Search</a></span></dt><dt><span class="section"><a href="#d0e3465">2.1.4. Returning a Single Node Instead of a Node List</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3490">2.2. <code class="function">getElementsByAttribute</code></a></span></dt><dt><span class="section"><a href="#d0e3521">2.3. <code class="function">getNodesByNodeType</code></a></span></dt><dt><span class="section"><a href="#d0e3578">2.4. <code class="function">getNodesByNodeValue</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3604">3. XML to and from Arrays</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3623">3.1. <code class="function">toArray</code></a></span></dt><dt><span class="section"><a href="#d0e3645">3.2. <code class="function">DOMIT_Utilities::fromArray</code></a></span></dt></dl></dd><dt><span class="section"><a href="#d0e3664">4. The nodetools Library</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3672">4.1. <code class="function">nodetools::parseAttributes</code></a></span></dt><dt><span class="section"><a href="#d0e3691">4.2. <code class="function">nodetools::moveUp</code></a></span></dt><dt><span class="section"><a href="#d0e3720">4.3. <code class="function">nodetools::moveDown</code></a></span></dt><dt><span class="section"><a href="#d0e3749">4.4. <code class="function">nodetools::nodeExists</code></a></span></dt><dt><span class="section"><a href="#d0e3782">4.5. <code class="function">nodetools::fromPath</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e3813">10. XML Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3821">1. Introduction to XML Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e3852">1.1. URIs, Namespace Prefixes, and Namespace Declarations</a></span></dt><dt><span class="section"><a href="#d0e3947">1.2. Default Namespace</a></span></dt><dt><span class="section"><a href="#d0e3969">1.3. Local Name</a></span></dt><dt><span class="section"><a href="#d0e3982">1.4. Qualified Name</a></span></dt><dt><span class="section"><a href="#d0e3998">1.5. DOM and XML Namespaces</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e4006">2. DOMIT! and XML Namespaces</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e4011">2.1. <code class="function">setNamespaceAwareness</code></a></span></dt><dt><span class="section"><a href="#d0e4023">2.2. <code class="function">declareNamespace</code></a></span></dt><dt><span class="section"><a href="#d0e4051">2.3. <code class="function">declareDefaultNamespace</code></a></span></dt><dt><span class="section"><a href="#d0e4079">2.4. <code class="function">getNamespaceDeclarationsInScope</code></a></span></dt><dt><span class="section"><a href="#d0e4096">2.5. <code class="function">getDefaultNamespaceDeclaration</code></a></span></dt><dt><span class="section"><a href="#d0e4112">2.6. <code class="function">copyNamespaceDeclarationsLocally</code></a></span></dt><dt><span class="section"><a href="#d0e4141">2.7. <code class="function">createElementNS</code></a></span></dt><dt><span class="section"><a href="#d0e4180">2.8. <code class="function">getElementsByTagNameNS</code></a></span></dt><dt><span class="section"><a href="#d0e4212">2.9. <code class="function">createAttributeNS</code></a></span></dt><dt><span class="section"><a href="#d0e4245">2.10. <code class="function">hasAttributeNS</code> and <code class="function">getAttributeNS</code></a></span></dt><dt><span class="section"><a href="#d0e4283">2.11. <code class="function">setAttributeNS</code></a></span></dt><dt><span class="section"><a href="#d0e4319">2.12. <code class="function">getAttributeNodeNS</code> and <code class="function">setAttributeNodeNS</code></a></span></dt><dt><span class="section"><a href="#d0e4365">2.13. <code class="function">removeAttributeNS</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d0e4398">11. XPath</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e4410">1. XPath Overview</a></span></dt><dt><span class="section"><a href="#d0e4416">2. <code class="function">selectNodes</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="#d0e4460">12. DOMIT! Roadmap</a></span></dt><dt><span class="chapter"><a href="#d0e4475">13. Contributing to DOMIT!</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e4"></a>Chapter&nbsp;1.&nbsp;Overview of XML</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e7"></a>1.&nbsp;Intro to XML</h2></div></div></div><p><a href="http://www.w3.org/TR/REC-xml/" target="_top">XML</a> (Extensible Markup Language) is a standard for encapsulating textual data. XML is strictly structured, but also human readable.</p><p>Having a strictly defined format makes it easier for computer programs (i.e., XML parsers) to build, extract, manipulate, and exchange the data. Since XML is written in human readable text and not binary format, it is much more convenient for people to work with on a daily basis.</p><p>This simple balance of structure and readability is one of the primary reasons that XML has seen such widespread adoption over recent years.</p><p>The following description of a person's cd music collection is one possible example of XML formatted text:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><p>As should be apparent from the example, XML has a tree-like structure. This is referred to as a <span class="emphasis"><em>Document</em></span>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e27"></a>2.&nbsp;Types of XML Content</h2></div></div></div><p>There are a varierty of different ways of demarcating content in an XML Document. The following sections presents a brief overview of some of these ways.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e32"></a>2.1.&nbsp;XML Elements</h3></div></div></div><p>An <span class="emphasis"><em>Element</em></span> in XML is a type of content whose primary purpose is to <span class="emphasis"><em>contain other content</em></span>. Elements are like bookends, and therefore consist of two parts: a <span class="emphasis"><em>start tag</em></span> and an <span class="emphasis"><em>end tag</em></span>.</p><p>Take a look at the first line of text in the cd library example: <code class="computeroutput">&lt;cdlibrary&gt;</code>.</p><p>This is an example of a start tag. A start tag always:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with a left angle bracket: <code class="computeroutput">&lt;</code></p></li><li><p>ends with a right angle bracket: <code class="computeroutput">&gt;</code></p></li><li><p>has a name: <code class="computeroutput">cdlibrary</code></p></li></ul></div><p>At the bottom of the XML document is an end tag, which has a slightly different format: <code class="computeroutput">&lt;/cdlibrary&gt;</code>.</p><p>An end tag always:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with a left angle bracket and a forward slash: <code class="computeroutput">&lt;/</code></p></li><li><p>ends with a right angle bracket: <code class="computeroutput">&gt;</code></p></li><li><p>has a name identical to its matching start tag: <code class="computeroutput">cdlibrary</code></p></li></ul></div><p>An XML element can contain other types of XML content, including other elements. For example, the <code class="computeroutput">&lt;person&gt;</code> element below contains a single <code class="computeroutput">&lt;name&gt;</code> element:</p><pre class="programlisting">&lt;person&gt;
  &lt;name&gt;John Heinstein&lt;/name&gt;
&lt;/person&gt;</pre><p>It is possible to have an element containing <span class="emphasis"><em>no</em></span> XML content. This is referred to as an <span class="emphasis"><em>empty element</em></span>. There is a shorthand notation for representing an empty element:</p><pre class="programlisting">&lt;someEmptyElement/&gt;</pre><p>The longhand equivalent of this is:</p><pre class="programlisting">&lt;someEmptyElement&gt;&lt;/someEmptyElement&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e119"></a>2.2.&nbsp;XML Attributes</h3></div></div></div><p>Take a look at the first <code class="computeroutput">cd</code> element in <code class="computeroutput">cdlibrary</code>:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;</pre><p>Some additional information is present in the start tag: <code class="computeroutput">discid="bb0c3c0c"</code>. This is a type of XML content referred to as an <span class="emphasis"><em>Attribute</em></span>. An attribute is used to store short, simple units of text.</p><p>An attribute always:</p><div class="itemizedlist"><ul type="disc"><li><p>contains a unique named key, such as: <code class="computeroutput">discid</code></p></li><li><p>followed by an equal sign: <code class="computeroutput">=</code></p></li><li><p>followed by a value contained in either single or double quotes: <code class="computeroutput">"bb0c3c0c"</code></p></li></ul></div><p>There can be multiple attributes in any start tag, as long as the attribute names are unique. For example:</p><pre class="programlisting">&lt;point x='10' y='35'/&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e162"></a>2.3.&nbsp;Character Data</h3></div></div></div><p>Textual XML content not stored in attributes is referred to as <span class="emphasis"><em>Character Data</em></span>. Character data is always contained within elements, as we can see in the following example from the <span class="emphasis"><em>cdlibrary</em></span> document</p><pre class="programlisting">&lt;name&gt;Robbie Fulks&lt;/name&gt;</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e175"></a>2.3.1.&nbsp;Illegal Characters</h4></div></div></div><p>There are two reserved characters which cannot be present in valid XML character data. These are the ampersand character (<code class="computeroutput">&amp;</code>) and the left angle bracket (<code class="computeroutput">&lt;</code>).</p><p>If either of these characters need to be present in XML text, it must be <span class="emphasis"><em>escaped</em></span>. This is done by substituting the <span class="emphasis"><em>entity equivalent</em></span> of the character.</p><div class="itemizedlist"><ul type="disc"><li><p>The entity equivalent of the ampersand (<code class="computeroutput">&amp;</code>) is the string <code class="computeroutput">&amp;amp</code>;</p></li><li><p>The entity equivalent of the left angle bracket (<code class="computeroutput">&lt;</code>) is the string <code class="computeroutput">&amp;lt;</code></p></li></ul></div><p>To represent the string <code class="computeroutput">x &lt;= y + 1</code> as character data, for example, one must escape the left angle bracket:</p><pre class="programlisting">&lt;relationship&gt;x &amp;lt;= y + 1&lt;/relationship&gt;</pre><p><em><span class="remark">Note: To allow attribute values to contain both single and double quotes, the apostrophe or single-quote character (<code class="computeroutput">'</code>) may be represented as <code class="computeroutput">&amp;apos;</code> and the double-quote character (<code class="computeroutput">"</code>) as <code class="computeroutput">&amp;quot;</code></span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e233"></a>2.3.2.&nbsp;CDATA Sections</h4></div></div></div><p>Sometimes your XML data contains many illegal characters that must be escaped -- such as when you need to store HTML content within XML content:</p><pre class="programlisting">&lt;htmlcode&gt;&amp;lt;img src="http://www.someurl.com/pic.jpg" /&gt;&lt;/htmlcode&gt;</pre><p>It is not only work intensive to escape many illegal characters, but the readability of your document suffers.</p><p>There is a special construct called a <span class="emphasis"><em>CDATA Section</em></span> that is reserved for demarcating text data that can be written in its literal form. The following example rewites the above <code class="computeroutput">&lt;htmlcode&gt;</code> example as a CDATA Section:</p><pre class="programlisting">&lt;htmlcode&gt;&lt;![CDATA[&lt;img src="http://www.someurl.com/pic.jpg"" /&gt;]]&gt;&lt;/htmlcode&gt;</pre><p>As you can see there is no need to escape the left angle bracket beginning the <code class="computeroutput">&lt;img</code> tag.</p><p>A CDATA Section always:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with the string <code class="computeroutput">&lt;![CDATA[</code></p></li><li><p>ends with the string <code class="computeroutput">]]&gt;</code></p></li></ul></div><p><em><span class="remark">Note: if the string <code class="computeroutput">]]&gt;</code> is contained within a CDATA Section, the right angle bracket (<code class="computeroutput">&gt;</code>)must be escaped as &amp;<code class="computeroutput">gt; </code>so that it will not be confused with the terminating CDATA Section string. </span></em></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e283"></a>2.4.&nbsp;Comments</h3></div></div></div><p>An XML <span class="emphasis"><em>Comment</em></span> is a construct for adding remarks to your XML. It is similar to an HTML comment in that it:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with the string <code class="computeroutput">&lt;!--</code></p></li><li><p>ends with the string <code class="computeroutput">--&gt;</code></p></li></ul></div><p>A comment could be added to the cdlibrary example like this:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;!-- Not many cds left after I got robbed --&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e306"></a>2.5.&nbsp;Processing Instructions</h3></div></div></div><p>An XML <span class="emphasis"><em>Processing Instruction</em></span> indicates to an application that it must perform some processing operation.</p><p>Every XML document is required to begin with a special type of processing instruction know as an <span class="emphasis"><em>XML Declaration</em></span> (in practice, the XML declaration is often omitted):</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;</pre><p>A processing instruction:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with the string <code class="computeroutput">&lt;?</code></p></li></ul></div><div class="itemizedlist"><ul type="disc"><li><p>followed by the <span class="emphasis"><em>target</em></span> of the operation (the application to which the operation is to be directed): e.g. <code class="computeroutput">xml</code></p></li><li><p>followed by the <span class="emphasis"><em>data</em></span> for the application to process: e.g. <code class="computeroutput">version="1.0"</code></p></li><li><p>ending with the string <code class="computeroutput">?&gt;</code></p></li></ul></div><p>Another example of a processing instruction is found in the declaration of PHP code within an HTML page:</p><pre class="programlisting">&lt;?php  
//code here
?&gt;</pre><p>The target "php" informs a web server to process the subsequent data with a PHP interpreter rather than as HTML code.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e359"></a>2.6.&nbsp;Document Type Declarations</h3></div></div></div><p>A <span class="emphasis"><em>Document Type Declaration</em></span> is a mechanism for defining what is an acceptable structure for an XML document. A <span class="emphasis"><em>validating XML parser</em></span> can compare an XML document to its DTD and determine whether it is valid or not.</p><p>A DTD follows the XML declaration and comes before any actual XML data.</p><p>The following is an example of a DTD for an XML document containing a single element named "foo":</p><pre class="programlisting">&lt;!DOCTYPE foo [
  &lt;!ELEMENT foo (#PCDATA)&gt;
]&gt;</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e377"></a>Chapter&nbsp;2.&nbsp;Overview of the DOM</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e380"></a>1.&nbsp;Intro to the DOM</h2></div></div></div><p>When one speaks of the <a href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html" target="_top">DOM (Document Object Model)</a>, one is not is not referring to XML <span class="emphasis"><em>per se</em></span>. Rather, the DOM is <span class="emphasis"><em>one of a number of different approaches to conceptualizing, parsing, and interacting with XML content</em></span>.</p><p>The DOM processes XML by creating an object called a <span class="emphasis"><em>Node</em></span> out of each unit of content in an XML document. Nodes are assembled into a hierarchical collection called a <span class="emphasis"><em>DOM Document</em></span>.</p><p>The entire XML document is held in memory at once, which allows the collection of nodes to be traversed easily. The DOM approach can, however, be memory intensive for larger XML documents.</p><p>The DOM also describes a number of methods and properties that allow the user to interact programatically with the nodes of a DOM Document.</p><p>We will be examining some of these methods and properties in the following tutorial.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e408"></a>2.&nbsp;Types of DOM Nodes</h2></div></div></div><p>The DOM specification delineates a number of different kinds of nodes, each of which correspond to the different kinds of XML content. A set of three node properties are used to distinguish one kind of node from another:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>node type</em></span>: an integer from 1 to 12 specifying the type of node</p></li><li><p><span class="emphasis"><em>node name</em></span>: the name of the node, can have various values depending on node type</p></li><li><p><span class="emphasis"><em>node value</em></span>: the value of the node, can various values depending on node type</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e429"></a>2.1.&nbsp;Document Nodes</h3></div></div></div><p>A <span class="emphasis"><em>Document Node</em></span> represents the DOM document itself -- the entire collection of nodes in a. It has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">9</code></p></li><li><p>a node name of <code class="computeroutput">#document</code></p></li><li><p>a node value of <code class="computeroutput">null</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e453"></a>2.2.&nbsp;Element Nodes</h3></div></div></div><p>An <span class="emphasis"><em>Element Node</em></span> represents an XML Element. Take for instance the following <code class="computeroutput">&lt;fullname&gt;</code> element:</p><pre class="programlisting">&lt;fullname&gt;John Heinstein&lt;/fullname&gt;</pre><p>This element has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">1</code></p></li><li><p>a node name of <code class="computeroutput">fullname</code></p></li><li><p>a node value of <code class="computeroutput">null</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e484"></a>2.3.&nbsp;Attribute Nodes</h3></div></div></div><p>An <span class="emphasis"><em>Attribute Node</em></span> represents an XML Attribute. Take for instance the following <code class="computeroutput">serial</code> attribute:</p><pre class="programlisting">&lt;item serial="123456"/&gt;</pre><p>This attribute has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">2</code></p></li><li><p>a node name of <code class="computeroutput">serial</code></p></li><li><p>a node value of <code class="computeroutput">123456</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e515"></a>2.4.&nbsp;Text Nodes</h3></div></div></div><p>A <span class="emphasis"><em>Text Node</em></span> represents XML Character Data that is not specified as a CDATA Section. Take for instance the text content bounded by the <code class="computeroutput">&lt;fullname&gt;</code> element:</p><pre class="programlisting">&lt;fullname&gt;John Heinstein&lt;/fullname&gt;</pre><p>This text node has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">3</code></p></li><li><p>a node name of <code class="computeroutput">#text</code></p></li><li><p>a node value of <code class="computeroutput">John Heinstein</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e546"></a>2.5.&nbsp;CDATA Section Nodes</h3></div></div></div><p>A <span class="emphasis"><em>CDATA Section Node</em></span> represents XML Character Data that is specified as a CDATA Section. Take the following CDATA Section:</p><pre class="programlisting">&lt;htmlcode&gt;&lt;![CDATA[&lt;img src="http://www.someurl.com/pic.jpg"" /&gt;]]&gt;&lt;/htmlcode&gt;</pre><p>This CDATA Section has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">4</code></p></li><li><p>a node name of <code class="computeroutput">#cdata-section</code></p></li><li><p>a node value of <code class="computeroutput">&lt;img src="http://www.someurl.com/pic.jpg"" /&gt;</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e574"></a>2.6.&nbsp;Comment Nodes</h3></div></div></div><p>A <span class="emphasis"><em>Comment Node</em></span> represents an XML comment. Take the following XML comment:</p><pre class="programlisting">&lt;!-- Not many cds left after I got robbed --&gt;</pre><p>This comment node has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">8</code></p></li><li><p>a node name of <code class="computeroutput">#comment</code></p></li><li><p>a node value of <code class="computeroutput"> Not many cds left after I got robbed </code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e602"></a>2.7.&nbsp;Processing Instruction Nodes</h3></div></div></div><p>A <span class="emphasis"><em>Processing Instruction Node</em></span> represents an XML processing instruction. The most common processing instruction that you will find in a DOM Document is the XML Declaration:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;</pre><p>This processing instruction node has:</p><div class="itemizedlist"><ul type="disc"><li><p>a node type of <code class="computeroutput">7</code></p></li><li><p>a node name of <code class="computeroutput">xml</code></p></li><li><p>a node value of <code class="computeroutput">version="1.0" </code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e630"></a>2.8.&nbsp;Document Type Declarations</h3></div></div></div><p>A <span class="emphasis"><em>Document Type Declaration</em></span> represents an XML document type declaration.</p><p>DOMIT! is a non-validating parser and therefore does not check the validity of an XML document against the DTD. It simply stores a string representation of the DTD.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e640"></a>3.&nbsp;The Structure of a DOM Document</h2></div></div></div><p>The nodes of a DOM Document are structured as a tree of branching nodes. The terminology to describe the relationship of these nodes is similar to how we would describe the relationship between individuals in a family tree.</p><p>Let us use the cdlibrary XML to illustrate this:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e649"></a>3.1.&nbsp;Child Nodes</h3></div></div></div><p>All nodes that are direct descendants of a node are referred to as its <span class="emphasis"><em>Child Nodes</em></span>.</p><p>Only nodes of type <span class="emphasis"><em>element</em></span> are permitted to contain a child nodes collection. Children themselves, however, can be of various node types, including element nodes, text and CDATA Section nodes, and comment nodes.</p><p>In the cdlibrary example:</p><div class="itemizedlist"><ul type="disc"><li><p>the <code class="computeroutput">&lt;cdlibrary&gt;</code> element contains three child nodes of type element (the three <code class="computeroutput">cd</code> nodes)</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  <span class="bold"><strong>&lt;cd discid="bb0c3c0c"&gt;</strong></span>
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  <span class="bold"><strong>&lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;</strong></span>
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  <span class="bold"><strong>&lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;</strong></span>
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  <span class="bold"><strong>&lt;/cd&gt;</strong></span>
&lt;/cdlibrary&gt;</pre></li><li><p>each <code class="computeroutput">&lt;cd&gt;</code> node contains two child nodes of type element (a <code class="computeroutput">&lt;name&gt;</code> node and a <code class="computeroutput">&lt;title&gt;</code> node) </p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  <span class="bold"><strong>&lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;</strong></span>
&lt;/cd&gt;</pre></li><li><p>each <code class="computeroutput">&lt;name&gt;</code> node contains one child node of type text</p><pre class="programlisting">&lt;name&gt;<span class="bold"><strong>Richard Thompson</strong></span>&lt;/name&gt;</pre></li><li><p>each <code class="computeroutput">&lt;title&gt;</code> node contains one child node of type text</p><pre class="programlisting">&lt;title&gt;<span class="bold"><strong>Laugh</strong></span>&lt;/title&gt;</pre></li></ul></div><p>A child node is referred to by its <span class="emphasis"><em>numerical index</em></span> in the child nodes collection. The first child node is generally assigned an index of 1, although for technical reasons some DOM implementations will start at 0.</p><p>If an element contains no children, it will still have an child nodes collection (that is empty).</p><p><em><span class="remark">Note: Attribute nodes are not included in the child nodes collection. These are in a separate collection reserved specifically for attributes.</span></em></p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e740"></a>3.1.1.&nbsp;First Child</h4></div></div></div><p>The <span class="emphasis"><em>First Child</em></span> is a DOM property that refers to the first child node in a child nodes collection.</p><p>In our cdlibrary example, the first child of each of the <code class="computeroutput">&lt;cd&gt;</code> nodes is the element node <code class="computeroutput">&lt;name&gt;</code>.</p><pre class="programlisting">&lt;cd discid="cf11720f"&gt;
  <span class="bold"><strong>&lt;name&gt;Keller Williams&lt;/name&gt;</strong></span>
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;</pre><p>If an element contains no child nodes, the first child is <code class="computeroutput">null</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e767"></a>3.1.2.&nbsp;Last Child</h4></div></div></div><p>The <span class="emphasis"><em>Last Child</em></span> is a DOM property that refers to the last child node in the child nodes collection.</p><p>In our cdlibrary example, the last child of each of the <code class="computeroutput">&lt;cd&gt;</code> nodes is the element node <code class="computeroutput">&lt;title&gt;</code>.</p><pre class="programlisting">&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  <span class="bold"><strong>&lt;title&gt;Laugh&lt;/title&gt;</strong></span>
&lt;/cd&gt;</pre><p>If an element contains no child nodes, the last child is <code class="computeroutput">null</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e794"></a>3.2.&nbsp;Parent Nodes</h3></div></div></div><p>In the same way that one can travel down the hierarchy of a DOM document via the child nodes collection, the DOM specifies a way to travel <span class="emphasis"><em>up</em></span> the hierarchy. The ancestor of any node is referred to as its <span class="emphasis"><em>Parent Node</em></span>.</p><p>In our cdlibrary example:</p><div class="itemizedlist"><ul type="disc"><li><p>the parent node of each <code class="computeroutput">&lt;cd&gt;</code> element is the <code class="computeroutput">&lt;cdlibrary&gt;</code> element</p></li><li><p>the parent node of each <code class="computeroutput">&lt;name&gt;</code> element is its containing <code class="computeroutput">&lt;cd&gt;</code> element</p></li><li><p>the parent node of each <code class="computeroutput">&lt;title&gt;</code> element is its containing <code class="computeroutput">&lt;cd&gt;</code> element</p></li><li><p>the parent node of the text contained in the <code class="computeroutput">&lt;name&gt;</code> element is the <code class="computeroutput">&lt;name&gt;</code> element</p></li><li><p>the parent node of the text contained in the <code class="computeroutput">&lt;title&gt;</code> element is the <code class="computeroutput">&lt;title&gt;</code> element</p></li></ul></div><p><em><span class="remark">Note: Attributes do not contain a reference to parent nodes.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e856"></a>3.3.&nbsp;Sibling Nodes</h3></div></div></div><p>The DOM specifies an explicit relationship between nodes that occupy the same level of a DOM tree. These nodes are referred to as <span class="emphasis"><em>Sibling Nodes</em></span>.</p><p>One might think of the relationship between sibling nodes as the links in a chain. Each node knows about the node immediately preceding it and the node immediately following it.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e866"></a>3.3.1.&nbsp;Previous Sibling</h4></div></div></div><p>The node immediately <span class="emphasis"><em>preceding</em></span> any node in a sibling chain is referred to as its <span class="emphasis"><em>Previous Sibling</em></span>.</p><p>In our cdlibrary example:</p><div class="itemizedlist"><ul type="disc"><li><p>the previous sibling of each <code class="computeroutput">&lt;title&gt;</code> element is the <code class="computeroutput">&lt;name&gt; </code>element</p></li><li><p>the previous sibling of each <code class="computeroutput">&lt;name&gt;</code> element is <code class="computeroutput">null</code></p></li></ul></div><p><em><span class="remark">Note: If a node has no previous sibling, there still exists a previous sibling reference, but it is <code class="computeroutput">null</code>.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e903"></a>3.3.2.&nbsp;Next Sibling</h4></div></div></div><p>The node immediately <span class="emphasis"><em>following</em></span> any node in a sibling chain is referred to as its <span class="emphasis"><em>Next Sibling</em></span>.</p><p>In our cdlibrary example:</p><div class="itemizedlist"><ul type="disc"><li><p>the next sibling of each <code class="computeroutput">&lt;name&gt;</code> element is the <code class="computeroutput">&lt;title&gt;</code> element</p></li><li><p>the next sibling of each <code class="computeroutput">&lt;title&gt;</code> element is <code class="computeroutput">null</code></p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e934"></a>3.4.&nbsp;Attribute Nodes</h3></div></div></div><p>Each element node contains an <span class="emphasis"><em>Attributes list</em></span>, or a reference to the collection of attributes assigned to it. In the following example, the <code class="computeroutput">&lt;item&gt;</code> element contains a list of five attributes:</p><pre class="programlisting">&lt;item desc="post" material="steel" length="120" diameter="5" price="0.75"/&gt; </pre><p>These attributes can be accessed either by <span class="emphasis"><em>name</em></span> or <span class="emphasis"><em>numerical index</em></span>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e955"></a>3.5.&nbsp;Owner Document</h3></div></div></div><p>Each node in a DOM Document -- with the exclusion of attribute nodes -- contains a reference to the DOM Document that contains it. This is referred to as the <span class="emphasis"><em>Owner Document</em></span> property of a node.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e963"></a>3.6.&nbsp;Document Element</h3></div></div></div><p>The root element of a DOM Document is always referred to as the <span class="emphasis"><em>Document Element</em></span>.</p><p>In our cdlibrary example, the document element would be the <code class="computeroutput">&lt;cdlibrary&gt;</code> node.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e976"></a>Chapter&nbsp;3.&nbsp;Installing DOMIT</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e979"></a>1.&nbsp;What is DOMIT!?</h2></div></div></div><p>DOMIT! is an <a href="http://www.w3.org/TR/REC-xml/" target="_top">XML</a> parser that is mostly consistent with the <a href="http://www.w3.org/TR/DOM-Level-2-Core/" target="_top">Document Object Model (DOM) Level 2 specification</a>.</p><p>DOMIT! is not an extension; it is written purely in <a href="http://www.php.net" target="_top">PHP</a> and should work in any PHP 4 or 5 environment, regardless of restrictions put in place by your web hosting provider.</p><p>It has been designed for speed and ease of use. However, because DOMIT! is composed of interpreted rather than compiled code, you may see sluggish performance with large XML files on a low-memory server.</p><p>DOMIT! must be used in conjunction with a <a href="http://www.saxproject.org/" target="_top">SAX</a> parser. By default, you have the option of using either the <a href="http://www.php.net/xml" target="_top">Expat parser</a> (available with most later distributions of PHP) or the <a href="http://www.engageinteractive.com/saxy/" target="_top">SAXY</a> parser - another purely PHP-based parser developed by Engage Interactive.</p><p>As of version 0.9, DOMIT! now includes a lightweight version named DOMIT! Lite, which is slightly faster, especially for larger documents. However, it does not handle parsing of the xml prolog, processing instructions, comments, and certain other functionality.</p><p>As of version 0.96, DOMIT! has support for <a href="http://www.w3.org/TR/REC-xml-names/" target="_top">XML namespaces</a>.</p><p>Version 0.98 brings PHP5 compatability.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1017"></a>2.&nbsp;Installing DOMIT!</h2></div></div></div><p>Since DOMIT! is not an extension, it requires no special setup on your web server. You will, however, need to have the following files present on your server filesystem:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="filename">xml_domit_include.php</code> - include file for DOMIT!, ensures that include paths are resolved properly.</p></li><li><p><code class="filename">xml_domit_shared.php</code> - shared code for DOMIT! and DOMIT! Lite</p></li><li><p><code class="filename">xml_domit_parser.php</code> - the main DOMIT! php file.</p></li><li><p><code class="filename">xml_domit_utilities.php</code> - required if you want to render your XML as a normalized (whitespace formatted) string or if you want to use the parseXML method of DOMIT_Document.</p></li><li><p><code class="filename">xml_domit_getelementsbypath.php</code> - required if you would like to search for elements in your DOMIT_Document using a path-based syntax.</p></li><li><p><code class="filename">xml_domit_nodemaps.php</code> - data structures that contain collections of nodes</p></li><li><p><code class="filename">xml_domit_nodetools.php</code> - a collection of tools to assist in XML processing</p></li><li><p><code class="filename">xml_domit_cache.php</code> - simple caching class for DOMIT! and DOMIT! Lite documents</p></li><li><p><code class="filename">xml_saxy_parser.php</code> - required if you would like to use the SAXY parser with DOMIT! instead of the Expat parser.</p></li><li><p><code class="filename">xml_domit_doctor.php</code> - class for repairing malformed xml</p></li><li><p><code class="filename">xml_domit_xpath.php</code> - experimental support for <a href="http://www.w3.org/TR/xpath" target="_top">XPath</a> queries</p></li><li><p><code class="filename">php_file_utilities.php</code> - generic file input / output utilities</p></li><li><p><code class="filename">php_http_client_generic.php</code> - generic http client class</p></li><li><p><code class="filename">php_http_client_include.php</code> - include file for http client class</p></li><li><p><code class="filename">php_http_connector.php</code> - helper class for php_http_client</p></li><li><p><code class="filename">php_http_exceptions.php</code> - http exceptions class</p></li><li><p><code class="filename">php_http_proxy.php</code> - http proxy class</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1111"></a>3.&nbsp;Installing DOMIT! Lite</h2></div></div></div><p>If you wish to use DOMIT! Lite, a leaner and somewhat faster (although fewer-featured) version of DOMIT!, you will require the following files:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="filename">xml_domit_lite_include.php</code> - include file for DOMIT! Lite, ensures that include paths are resolved properly.</p></li><li><p><code class="filename">xml_domit_shared.php</code> - shared code for DOMIT! and DOMIT! Lite.</p></li><li><p><code class="filename">xml_domit_lite_parser.php</code> - the main DOMIT! Lite php file.</p></li><li><p><code class="filename">xml_domit_utilities.php</code> - required if you want to render your XML as a normalized (whitespace formatted) string or if you want to use the parseXML method of DOMIT_Lite_Document.</p></li><li><p><code class="filename">xml_domit_getelementsbypath.php</code> - required if you would like to search for elements in your DOMIT_Lite_Document using a path-based syntax.</p></li><li><p><code class="filename">xml_domit_nodemaps.php</code> - data structures that contain collections of nodes</p></li><li><p><code class="filename">xml_domit_cache.php</code> - simple caching class for DOMIT! and DOMIT! Lite documents</p></li><li><p><code class="filename">xml_saxy_lite_parser.php</code> - required if you would like to use the SAXY Lite parser with DOMIT! Lite instead of the Expat parser.</p></li><li><p><code class="filename">xml_domit_doctor.php</code> - class for repairing malformed xml</p></li><li><p><code class="filename">php_file_utilities.php</code> - generic file input / output utilities</p></li><li><p><code class="filename">php_http_client.php</code> - generic http client class</p></li><li><p><code class="filename">php_http_client_include.php</code> - include file for http client class</p></li><li><p><code class="filename">php_http_connector.php</code> - helper class for php_http_client</p></li><li><p><code class="filename">php_http_exceptions.php</code> - http exceptions class</p></li><li><p><code class="filename">php_http_proxy.php</code> - http proxy class</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1192"></a>4.&nbsp;Including the DOMIT! Library in your Scripts</h2></div></div></div><p>To implement DOMIT! in your PHP scripts, include the file <code class="filename">xml_domit_include.php</code>:</p><pre class="programlisting">require_once('somepath/xml_domit_include.php');</pre><p>To implement DOMIT! Lite in your PHP scripts, include the file <code class="filename">xml_domit_lite_include.php</code>:</p><pre class="programlisting">require_once('somepath/xml_domit_lite_include.php');</pre></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1211"></a>Chapter&nbsp;4.&nbsp;Loading a DOMIT_Document</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1214"></a>1.&nbsp;Instantiating and Populating a DOMIT_Document</h2></div></div></div><p>In DOMIT!, a DOM Document is represented by the DOMIT_Document class.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1219"></a>1.1.&nbsp;Instantiating a DOMIT_Document</h3></div></div></div><p>You create an instance of the DOMIT_Document class in the same way as any other PHP class:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();</pre><p>A DOMIT! Lite document is instantiated like this:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Lite_Document();</pre><p>Once a document has been instantiated, it is ready to be populated with XML data.</p><p><em><span class="remark">Note: to ensure PHP 4 backwards compatability, it is necessary to include an ampersand (&amp;) symbol after the equal sign when returning a reference to a DOMIT_Document or any other DOMIT! object.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1236"></a>1.2.&nbsp;<code class="function">parseXML</code>: Populating a DOMIT_Document from a string variable</h3></div></div></div><p>If we wanted to create a DOMIT_Document out of a PHP string, we would use the <code class="function">parseXML</code> method. Take for instance, the cd collection XML described in the previous section:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document(); //instantiate document

//create string variable with XML text
$cdCollectionString = "&lt;?xml version="1.0"?&gt;&lt;cdlibrary&gt;&lt;cd discid=\"bb0c3c0c\"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;&lt;/cd&gt;
  &lt;cd discid=\"9b0ce70c\"&gt;&lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;&lt;/cd&gt;&lt;cd discid=\"cf11720f\"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;&lt;/cd&gt;
  &lt;/cdlibrary&gt;";

//use parseXML method to populate document
$success = $cdCollection-&gt;parseXML($cdCollectionString, true); //parse document</pre><p><code class="computeroutput"><code class="function">parseXML</code></code> returns <span class="bold"><strong>true</strong></span> if the parsing is successful</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1256"></a>1.3.&nbsp;<code class="function">loadXML</code>: Populating a DOMIT_Document from a file or url</h3></div></div></div><p>The <code class="function">loadXML</code> method of DOMIT_Document is used to load an XML string from a file or url. It uses an identical syntax to the <code class="function">parseXML</code> method:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");</pre><p>The above example parses a file from the file system.</p><p>To parse an url, you would specify the full HTTP address as the first parameter:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml");</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1278"></a>1.4.&nbsp;<code class="function">useSAXY</code>: Specifiying a SAX parser</h3></div></div></div><p>DOMIT! relies on an underlying SAX parser to parse XML data. You have the choice of one of two SAX parsers:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www.php.net/xml" target="_top">Expat</a> is a C-based SAX parser written by James Clark that comes bundled with most later distributions of PHP.</p></li><li><p><a href="http://www.engageinteractive.com/saxy/" target="_top">SAXY</a> is a pure PHP SAX parser written by <a href="http://www.engageinteractive.com/" target="_top">Engage Interactive</a> that comes bundled with DOMIT!</p></li></ul></div><p>The second parameter of both <code class="function">parseXML</code> and <code class="function">loadXML</code> allows you to specify a SAX parser. The <code class="function">useSAXY</code> parameter is a boolean whose default value is <span class="emphasis"><em>true</em></span>. Specifying false will check whether Expat is available and use it to parse and pass the XML data to DOMIT!:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml", false); //Expat specified</pre><p>If Expat cannot be detected, DOMIT! will revert to SAXY for its parsing.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1318"></a>1.5.&nbsp;Determining the base SAX parser</h3></div></div></div><p>To determine whether Expat or SAXY was used to generate a DOMIT_Document, you can use the <code class="function">parsedBy </code>method:</p><pre class="programlisting">$saxParser = $xmldoc-&gt;parsedBy();</pre><p>The parsedBy method returns a string with a value of either <span class="emphasis"><em>EXPAT</em></span> or <span class="emphasis"><em>SAXY</em></span>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1336"></a>2.&nbsp;Optional Settings for Loading XML Data</h2></div></div></div><p>Sometimes the default DOMIT! mechanism for populating a DOMIT!_Document is insufficient. This is particularly true when retrieving XML data from a remote location.</p><p>By default, DOMIT! uses the PHP function <code class="function">get_file_contents</code> or standard PHP file input streams to retrieve the contents of an XML file. However, both of these approaches can fail when passed a remote URL as the location of the XML file to parsed.</p><p>A number of additional options exist to deal with these possibilities.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1348"></a>2.1.&nbsp;<code class="function">useHTTPClient:</code> Forcing loadXML to use an HTTP Client</h3></div></div></div><p>As of version 1.0, DOMIT! comes bundled with the <code class="computeroutput">php_http_client</code> library, written by <a href="http://www.engageinteractive.com/" target="_top">Engage Interactive</a>. With the <code class="function">useHTTPClient</code> method, DOMIT! can be forced to establish a standard HTTP connection to the web server hosting the XML file:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();

//specify that an HTTP client should be used to retrieve XML
$xmldoc-&gt;useHTTPClient(true); 

//call loadXML method as usual
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml", false); </pre><p>The HTTP connection will be attempted on port 80.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1368"></a>2.2.&nbsp;<code class="function">setConnection</code>: Manually specifying HTTP connection parameters</h3></div></div></div><p>If you need to establish an HTTP connection to retrieve your XML data, but the <code class="function">useHTTPClient</code> method does not provide enough flexibility, the <code class="function">setConnection</code> method of DOMIT_Document can be used to manually set the parameters of the connection.</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$xmldoc-&gt;setConnection('http://www.engageinteractive.com', '/', '955');

//call loadXML method as usual
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml", false);</pre><p>In the above example, an HTTP connection will be established on port 955 of host <span class="emphasis"><em>http://www.engageinteractive.com</em></span>. You can also use a raw IP address for the host, such as <span class="emphasis"><em>http://198.162.0.10</em></span></p><p>Note that you can also pass in a user name and password to the <code class="function">setConnection</code> method, if you must use HTTP Authorization to establish your connection. For more about HTTP Authorization, please see the entry on the <code class="function">setAuthorization</code> method.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1398"></a>2.3.&nbsp;<code class="function">setAuthorization</code>: Using basic HTTP authorization with your connection</h3></div></div></div><p>The HTTP specification allows for a basic (i.e., not particularly secure) type of authorization called <span class="emphasis"><em>HTTP Authorization</em></span>. If the XML file that you require is protected by this sort of authentication, you can use the <code class="function">setAuthorization</code> method of DOMIT!. <code class="function"></code></p><p><code class="function">setAuthorization</code> is used in conjunction with the <code class="function">setConnection</code> method, and requires that you provide a plain text username and password:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$xmldoc-&gt;setConnection('http://www.engageinteractive.com', '/', '955');
$xmldoc-&gt;setAuthorization('johnheinstein', 'mypassword');

//call loadXML method as usual
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml", false);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1421"></a>2.4.&nbsp;<code class="function">setProxyConnection</code>: Retrieving XML data through a proxy server</h3></div></div></div><p>An <span class="emphasis"><em>HTTP proxy</em></span> is a server that acts as an intermediary between an HTTP client (a user's browser) and the Internet. It is used to enforce security, administrative control, and caching services. If you are behind a firewall, for instance, and must connect to a proxy server to access web based resources, then the <code class="function">setProxyConnection</code> method will allow you to access such data.</p><p>The <code class="function">setProxyConnection</code> method works inn exactly the same way as <code class="function">setConnection</code>:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$xmldoc-&gt;setProxyConnection('http://www.myproxyconnection.com', '/', '1060');

//call loadXML method as usual
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml", false);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1444"></a>2.5.&nbsp;<code class="function">setProxyAuthorization</code>: Using basic HTTP authorization with your proxy</h3></div></div></div><p>The <code class="function">setProxyAuthorization</code> is called in exactly the same way as <code class="function">setAuthorization</code>. Just provide a valid user name and password:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$xmldoc-&gt;setProxyConnection('http://www.myproxyconnection.com', '/', '1060');
$xmldoc-&gt;setProxyAuthorization('johnheinstein', 'mypassword');

//call loadXML method as usual
$success = $cdCollection-&gt;loadXML("http://www.engageinteractive.com/rssfeed.xml", false);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1459"></a>2.6.&nbsp;<code class="function">preserveWhiteSpace</code></h3></div></div></div><p>By default, when loading an XML document, DOMIT! removes what it considers insignificant whitespace -- such as the tabs between XML tags that are used for formatting purposes only.</p><p>Whitespace can be retained, however, if the following is called prior to loading or parsing:</p><pre class="programlisting">$cdCollection-&gt;preserveWhitespace(true);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1470"></a>2.7.&nbsp;<code class="function">appendEntityTranslationTable</code></h3></div></div></div><p>When DOMIT! parses or loads an XML Document, often entities are present which must be transformed into their corresponding character representations. Generally it is the responsibility of the DOCTYPE declaration to delineate these conversions.</p><p>However, DOMIT! is a non-validating parser, and is unaware of constraints placed on a document by the DOCTYPE.</p><p>The <code class="function">appendEntityTranslationTable</code> method is an alternate way of specifying character equivalents of entities.</p><p>It takes a single parameter -- an associative array of entities mapped to their equivalent characters. For example, if one wanted to instruct DOMIT! to convert all <code class="computeroutput">&amp;copy;</code> entities into <code class="computeroutput">&copy;</code> :</p><pre class="programlisting">//create translation table
$myTranslationTable = array('&amp;copy;' =&gt; '&copy;');

//pass table to document
$cdCollection-&gt;appendEntityTranslationTable($myTranslationTable);</pre><p></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1495"></a>3.&nbsp;Error Handling During and After Loading an XML Document</h2></div></div></div><p>When DOMIT! parses XML from a string or loads XML from a file, several methods can be used to handle non-conformant XML and retrieve error codes.</p><p>DOMIT! also allows you to set a custom error handler for runtime XML processing errors.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1502"></a>3.1.&nbsp;<code class="function">resolveErrors</code></h3></div></div></div><p>If the <code class="function">resolveErrors</code> method is called, DOMIT! will attempt to locate and fix any problems with improperly formatted XML code. The method must be called before parsing begins; just pass it a value of <span class="bold"><strong>true</strong></span>:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$cdCollection-&gt;resolveErrors(true);
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");</pre><p>Note that <code class="function">resolveErrors</code> may have an impact on speed, and should be used judiciously.</p><p>Currently, <code class="function">resolveErrors</code> only searches for and replaces ampersands that have not been encoded as <code class="computeroutput">&amp;amp;</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1528"></a>3.2.&nbsp;<code class="function">getErrorCode</code> and <code class="function">getErrorString</code></h3></div></div></div><p>If <code class="function">loadXML</code> or <code class="function">parseXML</code> return false, an error has occurred in processing. The methods <code class="function">getErrorCode</code> and <code class="function">getErrorString</code> can be used to diagnose where the problem lies.</p><p><code class="function">getErrorCode</code> returns a numerical description of the error, and <code class="function">getErrorString</code> returns a textual description of the error. For example:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$cdCollection-&gt;resolveErrors(true);
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //process XML
}
else {
  //an error has occurred; echo to browser
  echo "Error code: " . $cdCollection-&gt;getErrorCode();
  echo "\n&lt;br /&gt;";
  echo "Error string: " . $cdCollection-&gt;getErrorString();
}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1559"></a>3.3.&nbsp;DOMIT_DOMException::setErrorHandler</h3></div></div></div><p>If you would like to set a custom error handler for DOMIT! to handle runtime XML processing errors, you can use a static method of the <code class="function">DOMIT_DOMException</code> class: <code class="function">setErrorHandler</code>.</p><p>It takes a single parameter -- the method to handle the error.</p><p>The custom errorhandler method must have the following method signature...</p><p><code class="computeroutput">function myCustomErrorHandler($errorNum, $errorString) </code></p><p>...where <code class="computeroutput">$errorNum</code> is an integer signifying the number of the error, and <code class="function">$errorString</code> is a string giving a description of the error.</p><p>For example, if you wrote a function to handle your DOMIT! errors that looked like this:</p><pre class="programlisting">function myErrorHandler($errorNum, $errorString) {
  echo "The error number is " . $errorNum . " and " the error string is " . $errorString;
}</pre><p>You could invoke it like this:</p><pre class="programlisting">DOMIT_DOMException::setErrorHandler("myErrorHandler");</pre><p>If the <code class="function">myErrorHandler</code> function was a method of a class named <code class="function">ErrorHandlers</code> rather than a standalone function, you could invoke setErrorHandler like this:</p><pre class="programlisting">DOMIT_DOMException::setErrorHandler(array("ErrorHandlers", "myErrorHandler"));</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1606"></a>3.4.&nbsp;<code class="function">DOMIT_DOMException::setErrorMode</code></h3></div></div></div><p>The <code class="function">DOMIT_DOMException::setErrorMode</code> method allows you to define the behavior of DOMIT! when an exception occurs. It takes a single parameter -- an integer or interger constant representing the error mode:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>DOMIT_ONERROR_CONTINUE</strong></span> (1) - specifies that DOMIT! should continue processing after an exception occurs. This is the default behavior.</p></li><li><p><span class="bold"><strong>DOMIT_ONERROR_DIE</strong></span> (2) - specifies that DOMIT! should die and display the error message after an exception occurs.</p></li></ul></div><p>For example:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();

//sets DOMIT! to die on an exception
DOMIT_DOMException::setErrorMode(DOMIT_ONERROR_DIE);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1631"></a>3.5.&nbsp;<code class="function">DOMIT_DOMException::setErrorLog</code></h3></div></div></div><p>The <code class="function">DOMIT_DOMException::setErrorLog</code> method allows you to specify a file to which error messages are logged and timestamped. This is a useful feature for debugging XML parsing problems.</p><p>It takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>a boolean specifying whether logging should be turned on (true) or off (false)</p></li><li><p>a string containing the absolute or relative path of the error log file.</p></li></ul></div><p>The following example specifies that errors are to be logged to the file 'errorLog.txt':</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();

//specifies that error logging is to be enabled and the error log filename
DOMIT_DOMException::setErrorLog(true, 'errorLog.txt');</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1654"></a>Chapter&nbsp;5.&nbsp;Traversing a Document and Extracting Data</h2></div></div></div><p>Once a DOMIT_Document has been populated, you can use the standard DOM methods to extract and manipulate data in the XML tree. The following chapter illustrates how this can be done.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1659"></a>1.&nbsp;The Document Element Node</h2></div></div></div><p>You can acquire a reference to the document element node -- the root element in a DOM document -- using the<code class="function"> documentElement</code> keyword.</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //gets a reference to the root element of the cd collection
  $myDocumentElement =&amp; $cdCollection-&gt;documentElement;
}</pre><p>In the cd library example, the document element node is the node <code class="computeroutput">&lt;cdlibrary&gt;</code> .</p><p><em><span class="remark">Note: Always remember to use the reference (&amp;) operator in PHP4, or you will be returned a shallow copy of the childNodes array. Even if you are using PHP5, it is recommended for the sake of portability to other web servers that you use an ampersand anyway.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1677"></a>2.&nbsp;Displaying a Node as Text</h2></div></div></div><p>A text representation of a node and its contents can be displayed using the <code class="computeroutput"><code class="function">toString</code></code> and <code class="computeroutput"><code class="function">toNormalizedString</code></code> methods. The <code class="function">expandEmptyElementTags</code> method can be used to further tweak your output.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1693"></a>2.1.&nbsp;<code class="function">toString</code></h3></div></div></div><p>Take the document element node of the cd library example above. Once a reference to the <code class="computeroutput">&lt;cdlibrary&gt;</code> node has been obtained using the <code class="function">documentElement</code> keyword, we can see what it contains:</p><pre class="programlisting">$myDocumentElement =&amp; $cdCollection-&gt;documentElement;
echo $myDocumentElement-&gt;toString(true);</pre><p>The following string will be echoed to the browser window:</p><pre class="programlisting">&lt;cdlibrary&gt;&lt;cd discid="bb0c3c0c"&gt;&lt;name&gt;Robbie Fulks&lt;/name&gt;&lt;title&gt;Couples in Trouble&lt;/title&gt;&lt;/cd&gt;&lt;cd discid="9b0ce70c"&gt;&lt;name&gt;Richard Thompson&lt;/name&gt;&lt;title&gt;Mock Tudor&lt;/title&gt;&lt;/cd&gt;&lt;cd discid="cf11720f"&gt;&lt;name&gt;Keller Williams&lt;/name&gt;&lt;title&gt;Laugh&lt;/title&gt;&lt;/cd&gt;&lt;/cdlibrary&gt;</pre><p>The first parameter of <code class="function">toString</code> , if set to <span class="bold"><strong>true</strong></span>, converts special HTML characters into their encoded version (i.e. <span class="emphasis"><em>&amp;</em></span> into <span class="emphasis"><em>&amp;amp;</em></span>) so that they will display properly in a browser.</p><p>If you would like unconverted raw text to be output (for instance, when echoing to a command line interface) substitute a value of <span class="bold"><strong>false</strong></span>:</p><pre class="programlisting">echo $myDocumentElement-&gt;toString(false);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1733"></a>2.2.&nbsp;<code class="function">toNormalizedString</code></h3></div></div></div><p>One drawback of the <code class="function">toString</code> output is that it is not particularly readable, since all text of the node is compressed into one line. The <code class="function">toNormalizedString</code> method will output text that is much more nicely formatted:</p><pre class="programlisting">$myDocumentElement =&amp; $cdCollection-&gt;documentElement;
echo $myDocumentElement-&gt;toNormalizedString(true);</pre><p>The following string will be echoed to the browser window:</p><pre class="programlisting">&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><p>As with the <code class="function">toString</code> method, passing a value of <span class="bold"><strong>false</strong></span> into <code class="function">toNormalizedString</code> outputs text that is not formatted for HTML display.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1762"></a>2.3.&nbsp;expandEmptyElementTags</h3></div></div></div><p>When outputting XML using <code class="function">toString</code> or <code class="function">toNormalized</code> string, by default DOMIT! represents empty elements using the abbreviated convention:</p><pre class="programlisting">&lt;anEmptyElement /&gt;</pre><p>If you prefer the tags to be expanded instead, use the expandEmptyElementTags method:</p><pre class="programlisting">$xmldoc-&gt;expandEmptyElementTags(true);</pre><p>When using DOMIT! to render XHTML documents, often it is necessary to leave some tags unexpanded, such as the <code class="computeroutput">&lt;br /&gt;</code> tag. The <code class="function">expandEmptyElementTags</code> method allows you to pass in an array of exceptions to the expansion rule:</p><pre class="programlisting">//create array of exceptions to the empty element expansion rule
$expansionExceptions = array('br', 'hr');

//invoke expansion rule, passing in array of exceptions as second parameter
$xmldoc-&gt;expandEmptyElementTags(true, $expansionExceptions);</pre><p>This might result in output that looked like this:</p><pre class="programlisting">&lt;html&gt;
  &lt;body&gt;
    &lt;p&gt;This is a test&lt;/p&gt;
    &lt;p&gt;&lt;/p&gt;
    &lt;br /&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre><p></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1798"></a>3.&nbsp;Obtaining Node Type, Name, and Value</h2></div></div></div><p>In an earlier section, we learned that each node in a DOM document has three properties -- node type, node name, and node value -- that allows you to distinguish between it and other nodes.</p><p>These properties are accessible in DOMIT! with the <code class="function">nodeType</code>, <code class="function">nodeName</code>, and <code class="function">nodeValue</code> keywords.</p><p>To echo out these properties for the document element of the cdlibrary example, for instance, you would do this:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //gets a reference to the root element of the cd collection
  $myDocumentElement =&amp; $cdCollection-&gt;documentElement;

  //echo out node name
  echo "Node name: " . $myDocumentElement-&gt;nodeName;
  echo "\n&lt;br /&gt;";

  //echo out node type
  echo "Node type: " . $myDocumentElement-&gt;nodeType;
  echo "\n&lt;br /&gt;";

  //echo out node value
  echo "Node value: " . $myDocumentElement-&gt;nodeValue;
  echo "\n&lt;br /&gt;";
}</pre><p>The above example would display:</p><pre class="programlisting">cdlibrary
1
 </pre><p>Note that the last line is blank because the node value for an element is <span class="bold"><strong>null</strong></span>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e1829"></a>4.&nbsp;Traversing a DOM Tree</h2></div></div></div><p>You know how to:</p><div class="itemizedlist"><ul type="disc"><li><p>instantiate a DOMIT! document</p></li><li><p>populate a DOMIT! document using the <code class="computeroutput">loadXML</code> or <code class="computeroutput">parseXML</code> methods</p></li><li><p>obtain a reference to the document element</p></li><li><p>print the contents of a node, and</p></li><li><p>display the three basic node properties</p></li></ul></div><p>We will now learn how to access other parts of a document using such DOM constructs as child nodes, parent nodes, and next and previous siblings.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1858"></a>4.1.&nbsp;The <code class="computeroutput"><code class="function">childNodes</code></code> array, <code class="computeroutput"><code class="function">hasChildNodes</code></code>, and <code class="computeroutput"><code class="function">childCount</code></code></h3></div></div></div><p>As explained previously, each node in a DOM Document has a list of references to the nodes contained directly beneath it in the tree: its <span class="emphasis"><em>Child Nodes</em></span>.</p><p>In DOMIT!, the child nodes exist as a standard PHP array named <code class="computeroutput"><code class="function">childNodes</code></code>.</p><p>To grab a reference to the <code class="function">childNodes</code> array of a node, use the following syntax:</p><pre class="programlisting">//get a reference to the childNodes collection of the document element
$myChildNodes =&amp; $cdCollection-&gt;documentElement-&gt;childNodes;</pre><p><em><span class="remark">Note: When returning areference to the childNodes array in PHP4, always remember to use the reference (&amp;) operator, or you will be returned a shallow copy.</span></em></p><p>It is good practice, prior to grabbing a reference to the <code class="function">childNodes</code> array, to use the <code class="function">hasChildNodes</code> method to check if any child nodes exist:</p><pre class="programlisting">//ensure that there are childNodes before bothering to work with the childNodes array
if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {
  $myChildNodes =&amp; $cdCollection-&gt;documentElement-&gt;childNodes;
}</pre><p>The number of child nodes is stored in the <code class="computeroutput"><code class="function">childCount</code></code> property. You can use this value to traverse the <code class="function">childNodes</code> array and access its individual nodes:</p><pre class="programlisting">//ensure that there are childNodes before bothering to work with the childNodes array
if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get a reference to the childNodes collection of the document element
  $myChildNodes =&amp; $cdCollection-&gt;documentElement-&gt;childNodes;

  //get the total number of childNodes for the document element
  $numChildren =&amp; $cdCollection-&gt;documentElement-&gt;childCount;

  //iterate through the collection
  for ($i = 0; $i &lt; $numChildren; $i++) {

    //get a reference to the i childNode
    $currentNode =&amp; myChildNodes[$i];
    
    //echo out the node to browser
    echo ("Node $i contents are: \n&lt;br /&gt;" . 
      $currentNode-&gt;toNormalizedString(true) . "\n&lt;br /&gt;\n&lt;br /&gt;");
  }
}</pre><p>The above example will return:</p><pre class="programlisting">Node 1 contents are:
&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;

Node 2 contents are:
&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;

Node 3 contents are:
&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1918"></a>4.2.&nbsp;<code class="computeroutput"><code class="function">firstChild</code></code></h3></div></div></div><p>The <code class="computeroutput"><code class="function">childNodes</code></code> array is not the only means of accessing the children of a node.</p><p>The <code class="computeroutput"><code class="function">firstChild</code></code> property of a node returns a reference to a node's <span class="emphasis"><em>first</em></span> child node:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first child node of document element
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //echo out the node to browser
  echo ("The contents of the first child node are: \n&lt;br /&gt;" . 
      $firstChildNode-&gt;toNormalizedString(true));
  }
}</pre><p>The above example will return:</p><pre class="programlisting">The contents of the first child node are:
&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;</pre><p><em><span class="remark">Note: If there are no child nodes present, a value of <span class="bold"><strong>null</strong></span> is returned.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1950"></a>4.3.&nbsp;<code class="function">lastChild</code></h3></div></div></div><p>The <code class="computeroutput"><code class="function">lastChild</code></code> property of a node returns a reference to a node's <span class="emphasis"><em>last</em></span> child node:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to last child node
  $lastChildNode =&amp; $cdCollection-&gt;documentElement-&gt;lastChild;

  //echo out the node to browser
  echo ("The contents of the last child node are: \n&lt;br /&gt;" . 
      $lastChildNode-&gt;toNormalizedString(true));
  }
}</pre><p>The above example will return:</p><pre class="programlisting">The contents of the last child node are:
&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;</pre><p>If there are no child nodes present, a value of <span class="bold"><strong>null</strong></span> is returned.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e1974"></a>4.4.&nbsp;<code class="function">nextSibling</code></h3></div></div></div><p>Nodes that occupy the same level of a DOM tree are called <span class="emphasis"><em>siblings</em></span>. The DOM conceives of these nodes as being chained in a sequence, with each node aware of the node immediately preceding and immediately following it.</p><p>The <code class="computeroutput"><code class="function">nextSibling</code></code> property of a node returns a reference to the node <span class="emphasis"><em>prior</em></span> to it in the sibling chain.</p><p>In the cdlibrary example, the next sibling of the Robbie Fulks <code class="computeroutput">&lt;cd&gt;</code> node is the Richard Thompson <code class="computeroutput">&lt;cd&gt;</code> node. One would access it like this:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //get a reference to the next sibling (the Richard Thompson cd)
  $nextSiblingNode =&amp; $firstChildNode-&gt;nextSibling;

  //echo out the node to browser
  echo ("The contents of the next sibling are: \n&lt;br /&gt;" . 
      $nextSiblingNode-&gt;toNormalizedString(true));
  }
}</pre><p>The above example will return:</p><pre class="programlisting">The contents of the next sibling are:
&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;</pre><p>If there are no next sibling nodes present, a value of <span class="bold"><strong>null</strong></span> is returned.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2012"></a>4.5.&nbsp;<code class="function">previousSibling</code></h3></div></div></div><p>The <code class="computeroutput"><code class="function">lastSibling</code></code> property of a node returns a reference to the node <span class="emphasis"><em>after</em></span> it in the sibling chain.</p><p>In the cdlibrary example, the previous sibling of the Keller Williams <code class="computeroutput">&lt;cd&gt;</code> node is the Richard Thompson <code class="computeroutput">&lt;cd&gt;</code> node. One would access it like this:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to last cd node (the Keller Williams cd)
  $lastChildNode =&amp; $cdCollection-&gt;documentElement-&gt;lastChild;

  //get a reference to the previous sibling (the Richard Thompson cd)
  $previousSiblingNode =&amp; $lastChildNode-&gt;previousSibling;

  //echo out the node to browser
  echo ("The contents of the previous sibling are: \n&lt;br /&gt;" . 
      $previousSiblingNode-&gt;toNormalizedString(true));
  }
}</pre><p>The above example will return:</p><pre class="programlisting">The contents of the previous sibling are:
&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;</pre><p>If there are no previous sibling nodes present, a value of <span class="bold"><strong>null</strong></span> is returned.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2045"></a>4.6.&nbsp;<code class="function">parentNode</code></h3></div></div></div><p>As the name implies, the <code class="computeroutput"><code class="function">parentNode</code></code> property of a node returns a reference to the node <span class="emphasis"><em>one level above it</em></span> in the DOM tree.</p><p>In the cdlibrary example, the parent node of the Robbie Fulks <code class="computeroutput">&lt;cd&gt;</code> node is the document element <code class="computeroutput">&lt;cdlibrary&gt;</code> node. One would access it like this:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //get a reference to the parent (cdlibrary) node
  $myParentNode =&amp; $firstChildNode-&gt;parentNode;

  //echo out the node to browser
  echo ("The contents of the parent node of the Robbie Fulks cd node are: \n&lt;br /&gt;" . 
      $myParentNode-&gt;toNormalizedString(true));
  }
}</pre><p>The above example will return:</p><pre class="programlisting">The contents of the parent node of the Robbie Fulks cd node are:
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><p>If there is no parent node present, a value of <span class="bold"><strong>null</strong></span> is returned. Note that only the document element node will have no parent.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2078"></a>4.7.&nbsp;<code class="function">ownerDocument</code></h3></div></div></div><p>Each node in a DOM document -- with the the exception of attribute nodes -- is considered to be "owned" by that document.</p><p>Use the <code class="function">ownerDocument</code> property of a node to obtain a reference to the DOMIT! document:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //get a reference to the DOMIT document
  $myOwnerDocument =&amp; $firstChildNode-&gt;ownerDocument;
}</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2092"></a>5.&nbsp;Extracting Character Data</h2></div></div></div><p>Text nodes, CDATA Section nodes, and comment nodes belong to what is defined by the DOM as the CharacterData interface, which specifies a number of methods for obtaining the textual data. The following section describes some of these methods.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2097"></a>5.1.&nbsp;nodeValue</h3></div></div></div><p>The easiest way of getting the data from a text node, CDATA Section nodes, or comment node is through its <code class="function">nodeValue</code> property.</p><p><em><span class="remark">Note: A common error that many DOM newbies make is to confuse a text node with the element node that contains it. It is important to realize that a text node is always the <span class="emphasis"><em>child</em></span> of the containing element. </span></em></p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the &lt;name&gt; element of the Robbie Fulks cd
  $nameElement =&amp; $cdCollection-&gt;documentElement-&gt;childNodes[0]-&gt;firstChild;

  //get a reference to the text node
  //(this step has been broken into multiple steps to emphasize that
  //a text node must be distinguished from its containing element!)
  $nameTextNode =&amp; $nameElement-&gt;firstChild;

  //echo out the data in the text node 
  echo $nameTextNode-&gt;nodeName;
}</pre><p>The above example returns:</p><pre class="programlisting">Robbie Fulks</pre><p>If you prefer, you can condense the above steps into a single line:</p><pre class="programlisting">$myText  = $cdCollection-&gt;documentElement-&gt;childNodes[0]-&gt;firstChild-&gt;firstChild-&gt;nodeName;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2124"></a>5.2.&nbsp;getData</h3></div></div></div><p>The <code class="function">getData</code> method is a wrapper for the <code class="function">nodeValue</code> keyword and functions in exactly the same way:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the &lt;name&gt; element of the Robbie Fulks cd
  $nameElement =&amp; $cdCollection-&gt;documentElement-&gt;childNodes[0]-&gt;firstChild;

  //get a reference to the text node
  //(this step has been broken into multiple steps to emphasize that
  //a text node must be distinguished from its containing element!)
  $nameTextNode =&amp; $nameElement-&gt;firstChild;

  //echo out the data in the text node 
  echo $nameTextNode-&gt;getData();
}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2138"></a>5.3.&nbsp;getText</h3></div></div></div><p>In most cases, the <code class="function">getText</code> method functions identically to <code class="function">nodeValue</code> and <code class="function">getData</code>. You can simply substitute the word <span class="emphasis"><em>getText</em></span> for the word <span class="emphasis"><em>getData</em></span> in the previous example and the results will be the same.</p><p>However, <code class="function">getText</code> can also be called on an <span class="emphasis"><em>element</em></span>. In this case, the concatenated text of <span class="emphasis"><em>all children beneath the element</em></span> is returned. For instance:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //get a reference to the Robbie Fulks &lt;cd&gt; element
  $cdElement =&amp; $cdCollection-&gt;documentElement-&gt;childNodes[0];

  //get ALL text beneath the cd element ("name" text + "title" text)
  $childText = $cdElement-&gt;getText();

  //echo out the concatenated data 
  echo childText;
}</pre><p>The above example returns:</p><pre class="programlisting">Robbie FulksCouples in Trouble</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2177"></a>5.4.&nbsp;getLength</h3></div></div></div><p>The <code class="function">getLength</code> method indicates how many characters exist in a character data node:</p><pre class="programlisting">$numCharacters = $myTexNode-&gt;getLength();</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2188"></a>5.5.&nbsp;substringData</h3></div></div></div><p>The substringData method returns a specified subset of characters from a character data node.</p><p>It takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>offset</strong></span>: an integer specifying the starting character of the substring</p></li><li><p><span class="bold"><strong>count</strong></span>: an integer specifying how many characters from the offset should be included in the substring</p></li></ul></div><p>To extract the first name from the "Robbie Fulks" text node, for example, one would do this:</p><pre class="programlisting">$firstName = $rfTextNode-&gt;substringData(0,6);</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2211"></a>6.&nbsp;Accessing Attributes</h2></div></div></div><p>In a DOM document, attributes are accessed, by name, from their containing element. The DOMIT! methods <code class="function">hasAttribute</code> and <code class="function">getAttribute</code> can be used to extract attribute data.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2222"></a>6.1.&nbsp;<code class="function">hasAttribute</code></h3></div></div></div><p>To determine whether an element contains a particular attribute, you can use the <code class="function">hasAttribute</code> method. It takes a single string parameter -- the name of the attribute -- and returns either <span class="bold"><strong>true</strong></span> or <span class="bold"><strong>false</strong></span>:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode-&gt;hasAttribute("discid")) {
    echo ("I DO have a discid attribute");
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2240"></a>6.2.&nbsp;<code class="function">hasAttributes</code></h3></div></div></div><p>The <code class="function">hasAttributes</code> method returns true if an element contains at least one attribute.</p><pre class="programlisting">if ($someNode-&gt;hasAttributes()) {
    echo ("I have at least one attribute");
  }
  else {
    echo ("I have no attributes");
  }</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2252"></a>6.3.&nbsp;<code class="function">getAttribute</code></h3></div></div></div><p>To obtain the value of a named attribute, use the <code class="function">getAttribute</code> method. As with the <code class="function">hasAttribute</code> method, you pass in the attribute name:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode-&gt;hasAttribute("discid")) {

    //obtain the value of the discid attribute
    $attrValue = $firstChildNode-&gt;getAttribute("discid);

    //echo the value out to the browser
    echo ("Attribute value: " . $attrValue);
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}</pre><p>The above example returns:</p><pre class="programlisting">bb0c3c0c</pre><p><em><span class="remark">Note: If the attribute does not exist, an empty string (i.e., "") is returned.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2275"></a>6.4.&nbsp;<code class="function">getAttributeNode</code> and <code class="function">getValue</code></h3></div></div></div><p>The getAttribute method returns the <span class="emphasis"><em>value</em></span> of an attribute node. If you would like to obtain a <span class="emphasis"><em>reference to the node itself</em></span>, use the <code class="function">getAttributeNode</code> method.</p><p>To obtain the value of an attribute node, use either the <code class="function">getValue</code> method:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //determine whether it has an attribute named "discid" 
  if ($firstChildNode-&gt;hasAttribute("discid")) {

    //obtain a reference to the discid attribute node (don't forget the ampersand!)
    $attrNode =&amp; $firstChildNode-&gt;getAttributeNode("discid);

    //echo the value out to the browser
    echo ("The value of the discid attribute is: \n&lt;br /&gt;" . 
      $attrNode-&gt;getValue());
  }
  else {
    echo ("I DO NOT have a discid attribute");
  }
}</pre><p>The above example returns:</p><pre class="programlisting">The value of the discid attribute is:
bb0c3c0c</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2305"></a>6.5.&nbsp;The <code class="function">attributes</code> Keyword and Named Node Maps</h3></div></div></div><p>An attribute list is defined by the DOM specification as a <span class="emphasis"><em>Named Node Map</em></span>. This is a type of node collection that allows you to access its members either by name or by index.</p><p>Although the attribute specific methods are in most cases sufficient, there may be times when you do not know in advance the names of an elements attributes. Using the named node map methods, you can query ther list to find out this data.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2318"></a>6.5.1.&nbsp;The <code class="function">attributes</code> Keyword</h4></div></div></div><p>To obtain a reference to the attributes list /named node map of an element, use the <code class="function">attributes</code> keyword:</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //get a reference to the attributes list / named node map (don't forget the ampersand!)
  $attrList =&amp; $firstChildNode-&gt;attributes;
}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2332"></a>6.5.2.&nbsp;getLength, item, and getName</h4></div></div></div><p>The <code class="function">getLength</code> method of a named node map returns an integer indicating how many members belong to the attribute list.</p><p>The <code class="function">item</code> method of a named node map allows you to access a member by its numerical index (which is 0-based). In combination with the <code class="function">getLength</code> method, you can set up a loop through the members of an attribute list.</p><p>The <code class="function">getName</code> method will tell you the name of the node.</p><pre class="programlisting">if ($cdCollection-&gt;documentElement-&gt;hasChildNodes()) {

  //get reference to first cd node (the Robbie Fulks cd)
  $firstChildNode =&amp; $cdCollection-&gt;documentElement-&gt;firstChild;

  //get a reference to the attributes list / named node map (don't forget the ampersand!)
  $attrList =&amp; $firstChildNode-&gt;attributes;

  //determine the number of members in the attribute list
  $numAttributes = $attrList-&gt;getLength();

  //iterate through the list
  for ($i = 0; $i &lt; $numAttributes; $i++) {
    //get a reference to the attribute node at index i (don't forget the ampersand!)   
    $currAttr =&amp; $attrList-&gt;item(i);

    //echo out the name and value of the attribute
    echo "The attribute at index " . i . " is named: " . $currAttr-&gt;getName();
    echo "\n&lt;br /&gt; Its value is: " . $currAttr-&gt;getValue(); 
  }
}</pre><p>The above example returns:</p><pre class="programlisting">The attribute at index 1 is named: discid
Its value is: bb0c3c0c</pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2361"></a>7.&nbsp;Accessing the XML Prolog</h2></div></div></div><p>The <span class="emphasis"><em>XML Prolog</em></span> is a term referring to the XML Declaration and the Document Type Declaration.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2369"></a>7.1.&nbsp;<code class="function">getXMLDeclaration</code></h3></div></div></div><p>The XML declaration can be acquired with the <code class="function">getXMLDeclaration</code> method:</p><pre class="programlisting">$myXMLDecl =&amp; $xmldoc-&gt;getXMLDeclaration();</pre><p>A reference to a processing instruction node is returned.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2383"></a>7.2.&nbsp;Accessing the Document Type Declaration</h3></div></div></div><p>The Document Type Declaration can be acquired with the <code class="computeroutput">getDocType</code> method:</p><pre class="programlisting">$myDTD =&amp; $xmldoc-&gt;getDocType();</pre><p>A reference to a processing instruction node is returned.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2395"></a>Chapter&nbsp;6.&nbsp;Creating and Modifying a DOM Document</h2></div></div></div><p>The major strength of the Document Object Model is the ease with which the data in an XML document can be modified. The following chapter delineates how to use DOMIT! for creating, appending, inserting, replacing, removing, and altering XML data.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2400"></a>1.&nbsp;Creating Nodes</h2></div></div></div><p>Creating new XML nodes is accomplished using a set of DOMIT_Document factory methods. For the next subsections, we will assume that a new DOMIT_Document has already been created as follows:</p><pre class="programlisting">//include DOMIT! codebase
require_once('xml_domit_include.php');

//instantiate a new DOMIT! document
$xmldoc =&amp; new DOMIT_Document(); </pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2408"></a>1.1.&nbsp;<code class="function">createElement</code></h3></div></div></div><p>To create a new DOM element, use the <code class="function">createElement</code> method.</p><p>The <code class="function">createElement</code> method takes a single parameter -- the name of the element.</p><pre class="programlisting">$newElement =&amp; $xmldoc-&gt;createElement("cdlibrary");</pre><p><em><span class="remark">Note: Don't forget to include the ampersand for backwards compatibility with PHP4!</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2427"></a>1.2.&nbsp;<code class="function">createTextNode</code></h3></div></div></div><p>To create a new DOM text node, use the <code class="function">createTextNode</code> method.</p><p>The <code class="function">createTextNode</code> method takes a single parameter -- the text of the node.</p><pre class="programlisting">$myText = 'Here is some dummy text';

$newTextNode =&amp; $xmldoc-&gt;createTextNode($myText);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2444"></a>1.3.&nbsp;<code class="function">createCDATASection</code></h3></div></div></div><p>To create a new DOM CDATA Section, use the <code class="function">createCDATASection</code> method.</p><p>The <code class="function">createCDATASection</code> method takes a single parameter -- the text of the CDATA Section.</p><pre class="programlisting">$myText = 'Here are some illegal XML characters: &amp; &lt;';

$newCDATASection =&amp; $xmldoc-&gt;createCDATASection($myText);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2461"></a>1.4.&nbsp;<code class="function">createAttribute</code></h3></div></div></div><p>To create a new DOM attribute, use the <code class="function">createAttribute</code> method.</p><p>The <code class="function">createAttribute</code> method takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the name of the attribute</p></li><li><p>the value of the attribute</p></li></ul></div><pre class="programlisting">$newAttribute =&amp; $xmldoc-&gt;createAttribute("discid", "bb0c3c0c");</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2485"></a>1.5.&nbsp;<code class="function">createComment</code></h3></div></div></div><p>To create a new DOM comment, use the <code class="function">createComment</code> method.</p><p>The <code class="function">createComment</code> method takes a single parameter -- the text of the comment.</p><pre class="programlisting">$myCommentText = 'This is a comment';

$newCommentNode =&amp; $xmldoc-&gt;createComment($myCommentText);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2502"></a>1.6.&nbsp;<code class="function">createProcessingInstruction</code></h3></div></div></div><p>To create a new DOM processing instruction, use the <code class="function">createProcessingInstruction</code> method.</p><p>The <code class="function">createProcessingInstruction</code> method takes a two parameters -- the text of the target and the text of the data.</p><pre class="programlisting">//create target and data
$myTarget = 'xml';
$myData = 'version="1.0"';

//create processing instruction
$newProcessingInstructionNode =&amp; $xmldoc-&gt;createProcessingInstruction($myTarget, $myData);</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2519"></a>2.&nbsp;Appending Nodes</h2></div></div></div><p>Appending a node in the DOM means adding a new child node to the end of a node's child nodes list.</p><p>You can use the <code class="function">appendChild</code> method to append a node (and its children, if any exist) to a DOM Document or an element node.</p><p>The following example creates a <code class="computeroutput">&lt;cdlibrary&gt;</code> element and appends it to a new DOMIT_Document:</p><pre class="programlisting">//include DOMIT! codebase
require_once('xml_domit_include.php');

//instantiate a new DOMIT! document
$xmldoc =&amp; new DOMIT_Document(); 

//create cdlibrary node
$newNode =&amp; $xmldoc-&gt;createElement('cdlibrary');

//append cdlibrary node to new DOMIT_Document
$xmldoc-&gt;appendChild($newNode);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cdlibrary&gt;&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2542"></a>3.&nbsp;Setting the Document Element</h2></div></div></div><p>In the previous section, when the &lt;cdlibrary&gt; element was appended to the empty DOM document, it became the document element.</p><p>The <code class="function">setDocumentElement</code> method is another way of achieving the same result. For example:</p><pre class="programlisting">//include DOMIT! codebase
require_once('xml_domit_include.php');

//instantiate a new DOMIT! document
$xmldoc =&amp; new DOMIT_Document(); 

//create cdlibrary node
$newNode =&amp; $xmldoc-&gt;createElement('cdlibrary');

//append cdlibrary node to new DOMIT_Document
$xmldoc-&gt;setDocumentElement($newNode);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cdlibrary&gt;&lt;/cdlibrary&gt;</pre><p><code class="function">setDocumentElement</code> will overwrite an existing document element.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2564"></a>4.&nbsp;Setting Attributes</h2></div></div></div><p>The <code class="function">setAttribute</code> and <code class="function">setAttributeNode</code> methods are used to either add an attribute to an element, or change the value of an existing attribute. They are methods of element nodes only.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2575"></a>4.1.&nbsp;<code class="function">setAttribute</code></h3></div></div></div><p>The <code class="function">setAttribute</code> method takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the name of the attribute to be added</p></li><li><p>the value of the attribute to be appended</p></li></ul></div><p>The following example adds a <code class="computeroutput">discid</code> attribute to a <code class="computeroutput">&lt;cd&gt;</code> element:</p><pre class="programlisting">//create cd element
$newNode =&amp; $xmldoc-&gt;createElement('cd');

//add a discid attribute
$newNode-&gt;setAttribute('discid', 'bb0c3c0c');

//echo to browser
echo $newNode-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;&lt;/cd&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2607"></a>4.2.&nbsp;<code class="function">setAttributeNode</code></h3></div></div></div><p>The <code class="function">setAttribute</code> method also adds an attribute to an element. It takes a single parameter -- an attribute node:</p><pre class="programlisting">//create cd element
$newNode =&amp; $xmldoc-&gt;createElement('cd');

//create a discid attribute node
$newAttr =&amp; $xmldoc-&gt;createAttribute('discid', 'bb0c3c0c');

//add the attribute node to the element
$newNode-&gt;setAttributeNode($newAttr);

//echo to browser
echo $newNode-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;&lt;/cd&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2624"></a>5.&nbsp;Creating the cdlibrary XML Using DOMIT!</h2></div></div></div><p>We now have sufficient tools to create the cdlibrary example from scratch, using only DOMIT!</p><pre class="programlisting">//include DOMIT! codebase
require_once('xml_domit_include.php');

//instantiate a new DOMIT! document
$xmldoc =&amp; new DOMIT_Document(); 

//create XML declaration
$xmlDecl =&amp; $xmldoc-&gt;createProcessingInstruction('xml', 'version="1.0"');

//append XML declaration to new DOMIT_Document
$xmldoc-&gt;appendChild($xmlDecl);

//create cdlibrary node
$rootElement =&amp; $xmldoc-&gt;createElement('cdlibrary');

//append cdlibrary node to new DOMIT_Document
$xmldoc-&gt;appendChild($rootElement);

//CREATE FIRST CD ELEMENT AND CHILDREN
//create cd element
$cdElement_1 =&amp; $xmldoc-&gt;createElement('cd');

//add discid attribute
$cdElement_1-&gt;setAttribute('discid', 'bb0c3c0c');

//create name element
$nameElement =&amp; $xmldoc-&gt;createElement('name');

//create and append text node to name element
$nameElement-&gt;appendChild($xmldoc-&gt;createTextNode('Robbie Fulks'));

//append name element to cd element
$cdElement_1-&gt;appendChild($nameElement);

//create title element
$titleElement =&amp; $xmldoc-&gt;createElement('title');

//create and append text node to title element
$titleElement-&gt;appendChild($xmldoc-&gt;createTextNode('Couples in Trouble'));

//append title element to cd element
$cdElement_1-&gt;appendChild($titleElement);


//CREATE SECOND CD ELEMENT AND CHILDREN
//create cd element
$cdElement_2 =&amp; $xmldoc-&gt;createElement('cd');

//add discid attribute
$cdElement_2-&gt;setAttribute('discid', '9b0ce70c');

//create name element
$nameElement =&amp; $xmldoc-&gt;createElement('name');

//create and append text node to name element
$nameElement-&gt;appendChild($xmldoc-&gt;createTextNode('Richard Thompson'));

//append name element to cd element
$cdElement_2-&gt;appendChild($nameElement);

//create title element
$titleElement =&amp; $xmldoc-&gt;createElement('title');

//create and append text node to title element
$titleElement-&gt;appendChild($xmldoc-&gt;createTextNode('Mock Tudor'));

//append title element to cd element
$cdElement_2-&gt;appendChild($titleElement);


//CREATE THIRD CD ELEMENT AND CHILDREN
//create cd element
$cdElement_3 =&amp; $xmldoc-&gt;createElement('cd');

//add discid attribute
$cdElement_3-&gt;setAttribute('discid', 'cf11720f');

//create name element
$nameElement =&amp; $xmldoc-&gt;createElement('name');

//create and append text node to name element
$nameElement-&gt;appendChild($xmldoc-&gt;createTextNode('Keller Williams'));

//append name element to cd element
$cdElement_3-&gt;appendChild($nameElement);

//create title element
$titleElement =&amp; $xmldoc-&gt;createElement('title');

//create and append text node to title element
$titleElement-&gt;appendChild($xmldoc-&gt;createTextNode('Laugh'));

//append title element to cd element
$cdElement_3-&gt;appendChild($titleElement);

//APPEND CD ELEMENTS TO CDLIBARY ELEMENT
$rootElement-&gt;appendChild($cdElement_1);
$rootElement-&gt;appendChild($cdElement_2);
$rootElement-&gt;appendChild($cdElement_3);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2637"></a>6.&nbsp;Inserting Nodes</h2></div></div></div><p>If you need to add a child node somewhere other than the end of the child nodes list, you can use the <code class="function">insertBefore</code> method.</p><p><code class="function">insertBefore</code> takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>a reference to the node that is to be added</p></li><li><p>a reference to an existing child node, before which the insertion will occur</p></li></ul></div><p>If, continuing with the cdlibrary document from the previous example, we wished to insert a comment as the first child node of the <code class="computeroutput">&lt;cdlibrary&gt;</code> element, <code class="function">insertBefore</code> could be used:</p><pre class="programlisting">//create a comment
$myComment =&amp; $xmldoc-&gt;createComment('Not many cds left after I got robbed');

//insert the comment as the first child of the cdlibrary element
$rootElement-&gt;insertBefore($myComment, $rootElement-&gt;childNodes[0]);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;!--Not many cds left after I got robbed--&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2672"></a>7.&nbsp;Replacing Nodes</h2></div></div></div><p>Let's say that I traded my Robbie Fulks cd for a Charlie Hunter cd named "Songs From the Analog Playground", and I want to replace the old XML with a new cd node.</p><p>The <code class="function">replaceChild</code> method can be used to do this. It takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>a reference to the new node to be added</p></li><li><p>a reference to the node that is to be replaced</p></li></ul></div><pre class="programlisting">//CREATE NEW CHARLIE HUNTER CD ELEMENT AND CHILDREN
//create cd element
$cdElement_new =&amp; $xmldoc-&gt;createElement('cd');

//add discid attribute
$cdElement_new-&gt;setAttribute('discid', 'a30e4c0d');

//create name element
$nameElement =&amp; $xmldoc-&gt;createElement('name');

//create and append text node to name element
$nameElement-&gt;appendChild($xmldoc-&gt;createTextNode('Charlie Hunter'));

//append name element to cd element
$cdElement_new-&gt;appendChild($nameElement);

//create title element
$titleElement =&amp; $xmldoc-&gt;createElement('title');

//create and append text node to title element
$titleElement-&gt;appendChild($xmldoc-&gt;createTextNode('Songs From the Analog Playground'));

//append title element to cd element
$cdElement_new-&gt;appendChild($titleElement);

//REPLACE ROBIBIE FULKS CD NODE WITH CHARLIE HUNTER CD NODE
//(remember a comment has been added, so Robbie is the second child node)
$rootElement-&gt;replaceChild($cdElement_new, $rootElement-&gt;childNodes[1]);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;!--Not many cds left after I got robbed--&gt;
  &lt;cd discid="a30e4c0d"&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2697"></a>8.&nbsp;Removing Nodes</h2></div></div></div><p>The <code class="function">removeChild</code> method allows you to delete a node (and its children) from a DOM document. It takes a single parameter -- a reference to the node to be removed.</p><p>The following example removes the comment from the cdlibrary XML:</p><pre class="programlisting">$rootElement-&gt;removeChild($rootElement-&gt;firstChild);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="a30e4c0d"&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2714"></a>9.&nbsp;Removing Attributes</h2></div></div></div><p>An attribute can be deleted with either the <code class="function">removeAttribute</code> or <code class="function">removeAttributeNode</code> method.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2725"></a>9.1.&nbsp;<code class="function">removeAttribute</code></h3></div></div></div><p>An attribute can be removed with the <code class="function">removeAttribute</code> method. It takes a single parameter -- the name of the attribute to be removed.</p><p>The following example removes the <code class="computeroutput">discid</code> attribute from the Charlie Hunter <code class="computeroutput">&lt;cd&gt;</code> element:</p><pre class="programlisting">$rootElement-&gt;firstChild-&gt;removeAttribute('discid');

//echo to browser
echo $rootElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cdlibrary&gt;
  &lt;cd&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2749"></a>9.2.&nbsp;<code class="function">removeAttributeNode</code></h3></div></div></div><p>An attribute can also be removed with the <code class="function">removeAttributeNode</code> method. It takes a single parameter -- a reference to the attribute to be removed.</p><p>The following example removes the <code class="computeroutput">discid</code> attribute from the Charlie Hunter <code class="computeroutput">&lt;cd&gt;</code> element:</p><pre class="programlisting">//get reference to attribute to be removed
$attrToRemove =&amp; $rootElement-&gt;firstChild-&gt;getAttributeNode('discid');

//remove attribute
$rootElement-&gt;firstChild-&gt;removeAttributeNode($attrToRemove);

//echo to browser
echo $rootElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cdlibrary&gt;
  &lt;cd&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2773"></a>10.&nbsp;Setting Character Data</h2></div></div></div><p>There are a variety of methods available for working with character data nodes.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2778"></a>10.1.&nbsp;<code class="function">setText</code></h3></div></div></div><p>The <code class="function">setText</code> method allows you to modify the text of an existing text node, CDATA Section, or comment.</p><p>To change the title of the Keller Williams cd, for example, you would do this:</p><pre class="programlisting">//get reference to title text node of Keller Williams cd 
$titleTextNode =&amp; $rootElement-&gt;childNodes[2]-&gt;childNodes[1]-&gt;firstChild;

//modify title
$titleTextNode-&gt;setText('Loop');

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="a30e4c0d"&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Loop&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2797"></a>10.1.1.&nbsp;<code class="function">setText</code> When Called from an Element</h4></div></div></div><p>If <code class="function">setText</code> is called from an element instead of a text node, DOMIT! will check if the element has a child text node.</p><p>If the element <span class="emphasis"><em>has</em></span> a child text node, the text of that node will be set to the value specified in the <code class="function">setText</code> parameter.</p><p>If the element <span class="emphasis"><em>does not have</em></span> a child text node, a new text node will be created, appended to the element, and its node value set to the value specified in the <code class="function">setText</code> parameter. For instance:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//call setText on the element 
//(note that no child text node exists at this point, but one will be created)
$someElement-&gt;setText('Some sample text');

//echo to browser
echo $someElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;Some sample text&lt;/someElement&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2831"></a>10.2.&nbsp;<code class="function">splitText</code></h3></div></div></div><p>The <code class="function">splitText</code> method is accessible only from a text node. It allows you to split a text node into two text nodes, at a specified offset point. Both text nodes will be retained in the DOM tree as siblings.</p><p><code class="function">setText</code> takes a single integer parameter -- the character index at which the node is to be split.</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//echo childCount to browser
echo '$someElement has ' . $someElement-&gt;childCount . ' child nodes.';

/add a text node to the element 
$someElement-&gt;firstChild-&gt;splitText(5);

//echo childCount to browser
echo "\n&lt;br /&gt;";
echo 'After calling splitText, $someElement now has ' . $someElement-&gt;childCount . ' child nodes.';</pre><p>The result is:</p><pre class="programlisting">$someElement has 1 child nodes.
After calling splitText, $someElement now has 2 child nodes.</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2852"></a>10.3.&nbsp;<code class="function">normalize</code></h3></div></div></div><p>The <code class="function">normalize</code> method performs the opposite of the <code class="function">splitText</code> method: it collapses adjacent text nodes into a single text node.</p><p><code class="function">normalize</code> can be called from any element or the DOM document itself, and is called recursively on all nodes below the calling node.</p><p>The following example splits a text node using <code class="function">splitNode</code>, then uses <code class="function">normalize</code> to reverse the operation:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//echo childCount to browser
echo '$someElement has ' . $someElement-&gt;childCount . ' child nodes.';

/add a text node to the element 
$someElement-&gt;firstChild-&gt;splitText(5);

//echo childCount to browser
echo "\n&lt;br /&gt;";
echo 'After calling splitText, $someElement now has ' . $someElement-&gt;childCount . ' child nodes.';

//call normalize on element to reverse splitText
$someElement-&gt;normalize();

//echo childCount to browser
echo "\n&lt;br /&gt;";
echo 'After calling normalize, $someElement now has ' . $someElement-&gt;childCount . ' child nodes.';</pre><p>The result is:</p><pre class="programlisting">$someElement has 1 child nodes.
After calling splitText, $someElement now has 2 child nodes.
After calling normalize, $someElement now has 1 child nodes.</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2884"></a>10.4.&nbsp;<code class="function">appendData</code></h3></div></div></div><p>The <code class="function">appendData</code> method allows you to append text to a text node, CDATA Section, or comment node. For example:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//append more text
$someElement-&gt;firstChild-&gt;appendData(' plus more text.');

//echo to browser
echo $someElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;Some sample text plus more text.&lt;/someElement&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2901"></a>10.5.&nbsp;<code class="function">insertData</code></h3></div></div></div><p>The <code class="function">insertData</code> method allows you to insert text into a text node, CDATA Section, or comment node, as a specified offset.</p><p>It takes two parameters: an integer indicating the insertion pont, and a string comprising the text to be inserted. For example:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//insert some text
$someElement-&gt;firstChild-&gt;insertData(5, ' more');

//echo to browser
echo $someElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;Some more sample text&lt;/someElement&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2920"></a>10.6.&nbsp;<code class="function">replaceData</code></h3></div></div></div><p>The <code class="function">replaceData</code> method allows you to overwrite a substring of text in a text node, CDATA Section, or comment node.</p><p>It takes three parameters: an integer indicating the insertion pont, an integer specifying the number of characters from the insertion point to overwrite, and a string comprising the replacement text. For example:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//replace some text
$someElement-&gt;firstChild-&gt;replaceData(0, 4, 'A bit of');

//echo to browser
echo $someElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;A bit of sample text&lt;/someElement&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2939"></a>10.7.&nbsp;<code class="function">deleteData</code></h3></div></div></div><p>The d<code class="function">eleteData</code> method allows you to delete a substring of text in a text node, CDATA Section, or comment node.</p><p>It takes two parameters: an integer indicating the insertion pont, and an integer specifying the number of characters from the insertion point to delete. For example:</p><pre class="programlisting">//create a new element
$someElement =&amp; $xmldoc-&gt;createElement('someElement');

//add a text node to the element 
$someElement-&gt;setText('Some sample text');

//delete some text
$someElement-&gt;firstChild-&gt;deleteData(6, 7);

//echo to browser
echo $someElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;Some text&lt;/someElement&gt;</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2958"></a>Chapter&nbsp;7.&nbsp;Saving a DOM Document</h2></div></div></div><p>After modifying an XML document, you generally need to save it to the filesystem. This can be achieved using the <code class="function">saveXML</code> method.</p><p>saveXML takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the file path to save the document</p></li><li><p>a boolean specifying whether <code class="function">toNormalizedString</code> formatting should be applied to the saved XML</p></li></ul></div><p>To save the cdlibrary XML you would do this:</p><pre class="programlisting">$xmldoc-&gt;saveXML('/xml/cdcollection.xml', true)</pre></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2983"></a>Chapter&nbsp;8.&nbsp;Miscellaneous DOM Features</h2></div></div></div><p>The are a number of additional DOM methods and constructs that have not yet been covered in this tutorial. The following chapter illustrates these.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e2988"></a>1.&nbsp;<code class="function">cloneNode</code></h2></div></div></div><p>The cloneNode method allows you to make an copy of a node and its children. All data in the cloned node will be identical to its source node, but the nodes are considered separate objects.</p><p><code class="function">cloneNode</code> takes a single parameter -- a boolean that if set to <span class="bold"><strong>true</strong></span> will also clone all children of the node. The default value is <span class="bold"><strong>true</strong></span>.</p><p>Any type of node in a DOM document can be cloned.</p><p>The following example clones the first <code class="computeroutput">&lt;cd&gt;</code> element in the cdlibrary document and prints to the browser:</p><pre class="programlisting">//get reference to first cd node
$firstCDNode =&amp; $cdCollection-&gt;documentElement-&gt;childNodes[1]; 

//echo to browser
echo $firstCDNode-&gt;toNormalizedString(true);

//clone first cd node
$clonedCDNode =&amp; $firstCDNode-&gt;cloneNode(true);

//echo to browser
echo "\n&lt;br /&gt;\n&lt;br /&gt;" . $clonedCDNode-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;

&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3019"></a>2.&nbsp;<code class="function">getElementByID</code></h2></div></div></div><p>The <code class="function">getElementByID</code> method searches for elements with attributes of type ID, and returns an element with the specified value if one exists.</p><p>The DOM specification explains that by default, the search does not match on elements with an attribute <span class="emphasis"><em>named</em></span> "ID"; rather, it is an <span class="emphasis"><em>attribute type </em></span>that the method is looking for. The attribute type must either be:</p><div class="itemizedlist"><ul type="disc"><li><p>defined in the document type declaration, i.e.,</p><pre class="programlisting">&lt;!ATTLIST bar
    id ID #IMPLIED
  &gt;</pre></li><li><p>an attribute named id must be prefixed with the namespace <span class="emphasis"><em>xml</em></span></p><pre class="programlisting">&lt;someElement xml:id="12345" /&gt;</pre></li></ul></div><p>DOMIT! is a non-validating parser, so the first option is not available. DOMIT! does, however, recognize the second option. With the following xml document, for example...</p><pre class="programlisting">&lt;testDocument&gt;
  &lt;someElement xml:id="12345"&gt;The containing element is properly formatted for getElementByID&lt;/someElement&gt;
  &lt;anotherElement id="12345"&gt;The containing element is NOT properly formatted for getElementByID&lt;/anotherElement&gt;
&lt;/testDocument&gt;</pre><p>... the <code class="function">getElementByID</code> method will match only on the first child node:</p><pre class="programlisting">//instantiate and load XML
$xmldoc =&amp; new DOMIT_Document();
$success = $xmldoc-&gt;loadXML("testDocument.xml", true);

if ($success) {
  //search for element with an ID of "12345"
  $matchingNode =&amp; $xmldoc-&gt;getElementByID("12345");

  //echo matching node to browser if one exists
  if ($matchingNode != null) {
    echo $matchingNode-&gt;toNormalizedString(true);
  }
}</pre><p>The result is:</p><pre class="programlisting">&lt;someElement xml:id="12345"&gt;The containing element is properly formatted for getElementByID&lt;/someElement&gt;</pre><p>The <code class="function">getElementByID</code> method returns <span class="bold"><strong>null</strong></span> if no matching element is found.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3077"></a>2.1.&nbsp;<code class="function">getElementByID</code> and Strict vs. Tolerant mode</h3></div></div></div><p>Some may argue that the DOM specification for <code class="function">getElementByID</code> is too rigid for practical purposes. When parsing XHTML in particular, it is common to match on ID attributes that are not defined in such a way that DOMIT! or other non-validating parsers can effectively match on elements.</p><p>Given this, DOMIT! allows you to specify a <span class="emphasis"><em>tolerant</em></span> mode for <code class="function">getElementByID</code> searches. By passing in a second parameter of <span class="bold"><strong>false</strong></span>, DOMIT! will match on elements with attributes of "ID" and "id".</p><p>Take the following document, for example:</p><pre class="programlisting">&lt;testDocument&gt;
  &lt;anotherElement id="12345"&gt;The containing element is NOT properly formatted for getElementByID&lt;/anotherElement&gt;
&lt;/testDocument&gt;</pre><p>If <code class="function">getElementByID</code> is called:</p><pre class="programlisting">//instantiate and load XML
$xmldoc =&amp; new DOMIT_Document();
$success = $xmldoc-&gt;loadXML("testDocument.xml", true);

if ($success) {
  //search for element with an ID of "12345"
  $matchingNode =&amp; $xmldoc-&gt;getElementByID("12345");

  //echo matching node to browser if one exists
  if ($matchingNode != null) {
    echo $matchingNode-&gt;toNormalizedString(true);
  }
}</pre><p>The result is:</p><pre class="programlisting">&lt;anotherElement xml:id="12345"&gt;The containing element is NOT properly formatted for getElementByID&lt;/anotherElement&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3114"></a>3.&nbsp;<code class="function">getElementsByTagName</code></h2></div></div></div><p>The <code class="function">getElementsByTagName</code> method is similar to <code class="function">getElementByID</code>, in that it is a method for searching a DOM document for elements which match certain criteria.</p><p>In the case of <code class="function">getElementByTagName</code>, the <span class="emphasis"><em>name</em></span> of the element is matched on, and there can consequently be multiple matching elements.</p><p><code class="function">getElementsByTagName</code> takes a single parameter -- the tag name of the elements to match. The search is performed recursively through the entire subtree of the calling element.</p><p>If one searched the cdlibrary XML for elements named "cd", for example, three elements would be returned:</p><pre class="programlisting">$cdCollection =&amp; new DOMIT_Document();
$success = $cdCollection-&gt;loadXML("/xml/cdcollection.xml");

if ($success) {
  //use getElementsByTagName to gather all elements named "cd"
  $matchingNodes =&amp; $cdCollection-&gt;getElementsByTagName("cd");

  //if any matching nodes are found, echo to browser
  if ($matchingNodes != null) {
    echo $matchingNodes-&gt;toNormalizedString(true);
  }
}</pre><p>The result is a printout of the three matched cd elements:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;
&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;
&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3148"></a>4.&nbsp;Using NodeLists</h2></div></div></div><p>In the previous section, the <code class="function">getElementsByTagName</code> returned a collection of matching nodes. This collection is described by the DOM specification as a <span class="emphasis"><em>Node List</em></span>.</p><p>A node list is a collection of nodes accessible by numerical index. A number of methods are defined to access its members. Many of these are identical to those found in the previously discessed <span class="emphasis"><em>named node map</em></span>.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3164"></a>4.1.&nbsp;<code class="function">getLength</code> and <code class="function">item</code></h3></div></div></div><p>The <code class="function">getLength</code> and item <code class="function">methods</code> for a node list are identical to those for a named node map. You can use them to iterate through the node list using a for loop.</p><p>Take the previous <code class="function">getElementsByTagName</code> example, which returned three nodes. You can, for instance, loop through the node list and print out the <code class="computeroutput">discid</code> of each CD:</p><pre class="programlisting">//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =&amp; $cdCollection-&gt;getElementsByTagName("cd");

//if any matching nodes are found, loop through them and print out disc id
if ($matchingNodes != null) {
  
  //get total number of nodes in the list
  $total = $matchingNodes-&gt;getLength();

  //loop through node list 
  for ($i = 0; $i &lt; $total; $i++) {

    //get current node on list
    $currNode =&amp; $matchingNodes-&gt;item($i);

    //echo out discid
    echo $currNode-&gt;getAttribute('discid') . "\n&lt;br /&gt;";
  }
}</pre><p>The result is:</p><pre class="programlisting">bb0c3c0c
9b0ce70c
cf11720f</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3195"></a>4.2.&nbsp;<code class="function">appendNode</code> and <code class="function">removeNode</code></h3></div></div></div><p>The <code class="function">appendNode</code> method allows you to add a node to the end of the node list. The <code class="function">removeNode</code> method allows you to remove a node from the node list.</p><p>Both methods take a single parameter -- a reference to the node being appended or removed.</p><p>To <span class="emphasis"><em>append a node</em></span> to the cd node list from the above example, you could do this:</p><pre class="programlisting">//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =&amp; $cdCollection-&gt;getElementsByTagName("cd");

//create a new node
$newNode =&amp; $cdCollection-&gt;createElement("someElement");

//append the node to the node list
$matchingNodes-&gt;appendNode($newNode);

//echo to browser
echo $matchingNodes-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;
&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;
&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;
&lt;someElement /&gt;</pre><p>To r<span class="emphasis"><em>emove a node</em></span> from the cd node list from the above example, you could do this:</p><pre class="programlisting">//use getElementsByTagName to gather all elements named "cd"
$matchingNodes =&amp; $cdCollection-&gt;getElementsByTagName("cd");

//remove the first node from the node list
$matchingNodes-&gt;removeNode($matchingNodes-&gt;item(0));

//echo to browser
echo $matchingNodes-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="9b0ce70c"&gt;
  &lt;name&gt;Richard Thompson&lt;/name&gt;
  &lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;/cd&gt;
&lt;cd discid="cf11720f"&gt;
  &lt;name&gt;Keller Williams&lt;/name&gt;
  &lt;title&gt;Laugh&lt;/title&gt;
&lt;/cd&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3236"></a>4.3.&nbsp;childNodesAsNodeList</h3></div></div></div><p>According to the DOM specification, the child nodes of an element should be kept in a node list.</p><p>However, contrary to the specification, DOMIT! uses an array rather than a node list. This is to get around a deficiency in PHP 4, in which method calls cannot be chained together as one would normally expect with an object oriented programming language.</p><p>You cannot, for instance, do this in PHP4 (although you can in PHP5)...</p><pre class="programlisting">$myText = $xmldoc-&gt;documentElement-&gt;getChildNodes()-&gt;item(2)-&gt;getText();</pre><p>...although by using an array, it is possible to burrow deeply down into a document structure without splitting your code into multiple lines:</p><pre class="programlisting">$myText = $xmldoc-&gt;documentElement-&gt;childNodes[2]-&gt;getText();</pre><p>For those who are using PHP5 and would like child nodes to be returned in node list format, the <code class="function">childNodesAsNodeList</code> method can be used:</p><pre class="programlisting">$myText = $documentElement-&gt;childNodesAsNodeList()-&gt;item(2)-&gt;getText();</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3261"></a>5.&nbsp;<code class="function">importNode</code></h2></div></div></div><p>The <code class="function">importNode</code> method allows you to properly import a node into a DOM document which originated from another DOM document.</p><p>It takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the node to be imported</p></li><li><p>a boolean that, if <span class="bold"><strong>true</strong></span>, will also import all the nodes children (this is default behavior)</p></li></ul></div><p>Let's say we had two XML document. The first is the cd collection that we have been using throughout this tutorial. The second document contains a single cd that looks like this:</p><pre class="programlisting">&lt;cd discid="a30e4c0d"&gt;
  &lt;name&gt;Charlie Hunter&lt;/name&gt;
  &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
&lt;/cd&gt;</pre><p>If we instantiated these two XML documents, and wanted to add the contents of the <code class="computeroutput">cd</code> document to the <code class="computeroutput">cdlibrary</code> , we would first have to use <code class="function">importNode</code>:</p><pre class="programlisting">//instantiate and load first XML Document
$xmldoc1 =&amp; new DOMIT_Document();
$success1 = $xmldoc-&gt;loadXML("cdCollection.xml", true);

//instantiate and load second XML Document
$xmldoc2 =&amp; new DOMIT_Document();
$success2 = $xmldoc-&gt;loadXML("cd.xml", true);

//import contents of xmldoc2 into xmldoc1
$importedData =&amp; $xmldoc1-&gt;importNode($xmldoc2-&gt;documentElement);

//append contents of xmldoc2 to the cdCollection node
$xmldoc1-&gt;documentElement-&gt;appendChild($importedData);

//echo to browser
echo $xmldoc1-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="a30e4c0d"&gt;
    &lt;name&gt;Charlie Hunter&lt;/name&gt;
    &lt;title&gt;Songs From the Analog Playground&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e3306"></a>Chapter&nbsp;9.&nbsp;Custom DOMIT! Methods</h2></div></div></div><p>DOMIT! includes a number of non-DOM methods for XML processing.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3311"></a>1.&nbsp;<code class="function">getVersion</code></h2></div></div></div><p>The <code class="function">getVersion</code> method returns the version number of the current install of DOMIT!</p><pre class="programlisting">$myVersion = $xmldoc-&gt;getVersion();</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3323"></a>2.&nbsp;Searching for Nodes</h2></div></div></div><p>Although the <code class="function">getElementByID</code> and <code class="function">getElementsByTagName</code> methods are useful, often you need more sophisticated search options to simplify you XML code.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3334"></a>2.1.&nbsp;<code class="function">getElementsByPath</code></h3></div></div></div><p>The <code class="function">getElementsByPath</code> method allows you to search for elements in a document that match a "path"-like pattern that you provide.</p><p>The syntax is similar to an <a href="http://www.w3.org/TR/xpath" target="_top">XPath</a> query, although the range of patterns allowed by <code class="function">getElementsByPath</code> is far less sophisticated than the XPath specification permits.</p><p>The pattern takes the basic form of <span class="emphasis"><em>elementName/elementName</em></span>, where the forward slash represents a parent-child relationship. Either a node list, a single node, or null is returned</p><p><code class="function">getElementsByPath</code> can be called by any node. There are three basic ways that you can form a pattern:</p><div class="itemizedlist"><ul type="disc"><li><p>An <span class="bold"><strong>absolute path search</strong></span> can be performed by prefixing your pattern with the <span class="bold"><strong>/</strong></span> character. This type of search will start at the level of the document element node.</p></li><li><p>A <span class="bold"><strong>relative path search</strong></span> can be performed by <span class="emphasis"><em>omitting</em></span> the <span class="bold"><strong>/</strong></span> prefix from your pattern. This type of search will start at the level of the node which called getElementsByPath.</p></li><li><p>A <span class="bold"><strong>variable path search</strong></span> can be performed by prefixing your pattern with <span class="bold"><strong>//</strong></span> characters. This type of search will find all matching elements, regardless of their position in the node hierarchy.</p></li></ul></div><p>Let's try an example of each with our cdlibrary XML:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e3396"></a>2.1.1.&nbsp;Absolute Path Search</h4></div></div></div><p>The pattern for an absolute path search begins with a forward slash, meaning that the search will begin at the level of the document element node -- no matter what level the calling node resides.</p><p>To perform an absolute search for all <code class="computeroutput">&lt;title&gt;</code> elements, one would do this:</p><pre class="programlisting">//use getElementsByPath to retrieve all title elements
$myNodeList =&amp; $cdCollection-&gt;getElementsByPath("/cdlibrary/cd/title");

//echo to browser
echo $myNodeList-&gt;toNormalizedString(true);</pre><p>The result is a listing of the three found <code class="computeroutput">&lt;title&gt;</code> nodes:</p><pre class="programlisting">&lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;title&gt;Laugh&lt;/title&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e3417"></a>2.1.2.&nbsp;Relative Path Search</h4></div></div></div><p>The pattern for a relative path search does not contain a beginning forward slash. The search will begin at the level of the calling node.</p><p>To perform an relative search for all <code class="computeroutput">&lt;name&gt;</code> elements which are children of <code class="computeroutput">&lt;cd&gt;</code> elements which are children of the <code class="computeroutput">&lt;cdlibrary&gt;</code> element, one would do this:</p><pre class="programlisting">//use getElementsByPath to retrieve all name elements which are children of 
//cd elements which are children of the cdlibrary element
$myNodeList =&amp; $cdCollection-&gt;documentElement-&gt;getElementsByPath("cd/name");

//echo to browser
echo $myNodeList-&gt;toNormalizedString(true);</pre><p>The result is a listing of the three found <code class="computeroutput">&lt;name&gt;</code> nodes:</p><pre class="programlisting">&lt;name&gt;Robbie Fulks&lt;/name&gt;
&lt;name&gt;Richard Thompson&lt;/name&gt;
&lt;name&gt;Keller Williams&lt;/name&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e3444"></a>2.1.3.&nbsp;Variable Path Search</h4></div></div></div><p>The pattern for a variable path search begins with a double forward slash. Each element in the document is be considered a starting point for the search.</p><p>To perform a variable search for all <code class="computeroutput">&lt;title&gt;</code> elements in the document, one would do this:</p><pre class="programlisting">//use getElementsByPath to retrieve all title elements in cdlibrary
$myNodeList =&amp; $cdCollection-&gt;getElementsByPath("//title");

//echo to browser
echo $myNodeList-&gt;toNormalizedString(true);</pre><p>The result is a listing of the three found <code class="computeroutput">&lt;title&gt;</code> nodes:</p><pre class="programlisting">&lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;title&gt;Mock Tudor&lt;/title&gt;
&lt;title&gt;Laugh&lt;/title&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e3465"></a>2.1.4.&nbsp;Returning a Single Node Instead of a Node List</h4></div></div></div><p>If you would like a single node to be returned by <code class="function">getElementsByPath</code>, rather than the entire node list of matching elements, you can specify the index of the requested node by passing an integer as the second parameter of <code class="function">getElementsByPath</code>.</p><p>In accordance with the XPath specification, the index that you specify is 1-based.</p><p>To return the first <code class="computeroutput">&lt;cd&gt;</code> node of the cdlibrary example, you could do this:</p><pre class="programlisting">//use getElementsByPath to retrieve the first cd element in cdlibrary
$myElement =&amp; $cdCollection-&gt;getElementsByPath("/cdlibrary/cd", 1);

//echo to browser
if ($myElement != null) {
  echo $myElement-&gt;toNormalizedString(true);
}</pre><p>The result is:</p><pre class="programlisting">&lt;cd discid="bb0c3c0c"&gt;
  &lt;name&gt;Robbie Fulks&lt;/name&gt;
  &lt;title&gt;Couples in Trouble&lt;/title&gt;
&lt;/cd&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3490"></a>2.2.&nbsp;<code class="function">getElementsByAttribute</code></h3></div></div></div><p>The <code class="function">getElementsByAttribute</code> method allows you to retrieve a node list of elements, each of which contain an attribute that matches the specified name and value. This is a useful improvement over the <code class="function">getElementByID</code> method, since it does not require you to be bound to a narrow definition of attribute type or name.</p><p>To obtain a node list of all elements containing an attribute named 'myAttr' and a value of '3', for example, you would do this:</p><pre class="programlisting">//get node list of elements containing myAttr="3"
$myNodeList =&amp; $xmldoc-&gt;getElementsByAttribute('myAttr', '3');</pre><p>There is a third parameter available for <code class="function">getElementsByAttribute</code>, a boolean which if set to <span class="bold"><strong>true</strong></span> will return the<span class="emphasis"><em> first matching element</em></span> rather than an entire node list of elements:</p><pre class="programlisting">//get first matching elements containing myAttr="3"
$myElement =&amp; $xmldoc-&gt;getElementsByAttribute('myAttr', '3', true);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3521"></a>2.3.&nbsp;<code class="function">getNodesByNodeType</code></h3></div></div></div><p>The <code class="function">getNodesByNodeType</code> method allows you to search the document tree for nodes of a specific <span class="emphasis"><em>node type</em></span>.</p><p>You can specify a node type using one of the following DOMIT! constants:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="function">DOMIT_ELEMENT_NODE</code> (an integer value of 1)</p></li><li><p><code class="function">DOMIT_TEXT_NODE</code> (an integer value of 3)</p></li><li><p><code class="function">DOMIT_CDATA_SECTION_NODE</code> (an integer value of 4)</p></li><li><p><code class="function">DOMIT_PROCESSING_INSTRUCTION_NODE</code> (an integer value of 7)</p></li><li><p><code class="function">DOMIT_COMMENT_NODE</code> (an integer value of 8)</p></li><li><p><code class="function">DOMIT_DOCUMENT_NODE</code> (an integer value of 9)</p></li></ul></div><p>You must also pass in as the second parameter a context node - a node from which the search should start.</p><p>The following example returns a node list of all text nodes in the cdlibrary example:</p><pre class="programlisting">//find all text nodes in cdlibrary
$myTextNodeList =&amp; $cdCollection-&gt;getNodesByNodeType(DOMIT_TEXT_NODE, $cdCollection);

//echo to browser
echo $myTextNodeList-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">Robbie Fulks
Couples in Trouble
Richard Thompson
Mock Tudor
Keller Williams
Laugh</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3578"></a>2.4.&nbsp;<code class="function">getNodesByNodeValue</code></h3></div></div></div><p>The <code class="function">getNodesByNodeValue</code> method allows you to search the document tree for nodes of a specific <span class="emphasis"><em>node value</em></span>.</p><p>This is especially useful for finding text or CDATA Section nodes containing a certain text value.</p><p>You must pass in the node value that you are searching for as well as a context node - a node from which the search should start.</p><p>The following example returns a node list of all nodes in the current document with a node value of "Robbie Fulks":</p><pre class="programlisting">//find all text nodes with a value of "Robbie Fulks" in cdlibrary
$myTextNodeList =&amp; $cdCollection-&gt;getNodesByNodeValue("Robbie Fulks", $cdCollection);

//get first match
$firstItem =&amp; $myTextNodeList-&gt;item(0);

//echo parent node to browser
echo $firstItem-&gt;parentNode-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;name&gt;Robbie Fulks&lt;/name&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3604"></a>3.&nbsp;XML to and from Arrays</h2></div></div></div><p>Sometimes it is useful to convert an XML document into a PHP array, or to import a PHP array as an XML document.</p><p>DOMIT! provides two methods to accomplish this: <code class="function">toArray</code>, and <code class="function">DOMIT_Utilities::fromArray</code>.</p><p><em><span class="remark">Note: It may be faster to use the PHP/Expat method <a href="http://www.php.net/manual/en/function.xml-parse-into-struct.php" target="_top">xml_parse_into_struct</a> instead of the DOMIT! array methods when converting XML to arrays.</span></em></p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3623"></a>3.1.&nbsp;<code class="function">toArray</code></h3></div></div></div><p>The <code class="function">toArray</code> method converts an xml node and its children to an array.</p><p>To convert the first <code class="computeroutput">&lt;cd&gt;</code> element of the cdlibrary example to an array, you would do this:</p><pre class="programlisting">//convert first &lt;cd&gt; element to array
$myArray =&amp; $cdCollection-&gt;documentElement-&gt;firstChild-&gt;toArray();

//echo to browser
print "&lt;pre&gt;";
print_r($myArray);
print "&lt;/pre&gt;";</pre><p>The result is:</p><pre class="programlisting">Array
(
    [cd] =&gt; Array
        (
            [attributes] =&gt; Array
                (
                    [discid] =&gt; bb0c3c0c
                )

            [0] =&gt; Array
                (
                    [name] =&gt; Array
                        (
                            [attributes] =&gt; Array
                                (
                                )

                            [0] =&gt; Robbie Fulks
                        )

                )

            [1] =&gt; Array
                (
                    [title] =&gt; Array
                        (
                            [attributes] =&gt; Array
                                (
                                )

                            [0] =&gt; Couples in Trouble
                        )

                )

        )

)</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3645"></a>3.2.&nbsp;<code class="function">DOMIT_Utilities::fromArray</code></h3></div></div></div><p>The <code class="function">DOMIT_Utilities::fromArray</code> method generates a node tree from an array and appends it to the specified document or node.</p><p>The convention follows that of the fromArray method in the minixml library:</p><pre class="programlisting">//Create an array to represent a person Bob
$bob = array(
  'name' =&gt; array( 
    'first' =&gt; 'Bob',
    'last' =&gt; 'Roberts'
  ),
  'age' =&gt; 35,
  'email' =&gt; 'hide@address.com',
  'location' =&gt; array(
    'streetaddr' =&gt; '123 Skid Row',
    'city' =&gt; 'Dark City',
    'state' =&gt; 'DN',
    'country' =&gt; 'XNE',
  ),
);


//Create another array to represent a person Mary
$mary = array(
  'name' =&gt; array( 
    'first' =&gt; 'Mary',
    'last' =&gt; 'Zlipsakis'
  ),
  'age' =&gt; 94,
  'location' =&gt; array(
    'streetaddr'=&gt; '54343 Park Ave',
    'city' =&gt; 'SmallVille',
    'state' =&gt; 'DN',
    'country' =&gt; 'XNE',
  ),
  'icecream' =&gt; 'vanilla',
);


//Create a big array that contains all our people
$xmlArray = array();
$xmlArray["people"]["person"] = array();

array_push($xmlArray["people"]["person"], $mary);
array_push($xmlArray["people"]["person"], $bob);

//instatiate a DOMIT! document
require_once('xml_domit_include.php');
$xmldoc =&amp; new DOMIT_Document();

//require DOMIT_Utilities file
require_once('xml_domit_utilities.php');

//use fromArray to populate document
DOMIT_Utilities::fromArray($xmldoc, $xmlArray);

//echo to browser
echo $xmldoc-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;people&gt;
    &lt;person&gt;
        &lt;name&gt;
            &lt;first&gt;Mary&lt;/first&gt;
            &lt;last&gt;Zlipsakis&lt;/last&gt;
        &lt;/name&gt;
        &lt;age&gt;94&lt;/age&gt;
        &lt;location&gt;
            &lt;streetaddr&gt;54343 Park Ave&lt;/streetaddr&gt;
            &lt;city&gt;SmallVille&lt;/city&gt;
            &lt;state&gt;DN&lt;/state&gt;
            &lt;country&gt;XNE&lt;/country&gt;
        &lt;/location&gt;
        &lt;icecream&gt;vanilla&lt;/icecream&gt;
    &lt;/person&gt;
    &lt;person&gt;
        &lt;name&gt;
            &lt;first&gt;Bob&lt;/first&gt;
            &lt;last&gt;Roberts&lt;/last&gt;
        &lt;/name&gt;
        &lt;age&gt;35&lt;/age&gt;
        &lt;email&gt;hide@address.com&lt;/email&gt;
        &lt;location&gt;
            &lt;streetaddr&gt;123 Skid Row&lt;/streetaddr&gt;
            &lt;city&gt;Dark City&lt;/city&gt;
            &lt;state&gt;DN&lt;/state&gt;
            &lt;country&gt;XNE&lt;/country&gt;
        &lt;/location&gt;
    &lt;/person&gt;
&lt;/people&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3664"></a>4.&nbsp;The nodetools Library</h2></div></div></div><p>The <code class="function">nodetools</code> library is a set of helper utilities for processing nodes.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3672"></a>4.1.&nbsp;<code class="function">nodetools::parseAttributes</code></h3></div></div></div><p>The <code class="function">nodetools::parseattributes</code> method parses an attribute string into an array of key / value pairs.</p><p>For example:</p><pre class="programlisting">//require the nodetools library
require_once('xml_domit_nodetools.php');

//build a sample attribute string
$myAttrString = 'x="27" y="12"';

//parse into an array
$myArray = nodetools::parseattributes($myAttrString);

//echo to browser
echo "&lt;pre&gt;";
print_r($myArray);
echo "&lt;/pre&gt;";</pre><p>The result is:</p><pre class="programlisting">Array
(
    [x] =&gt; 27
    [y] =&gt; 12
)</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3691"></a>4.2.&nbsp;<code class="function">nodetools::moveUp</code></h3></div></div></div><p>The <code class="function">nodetools::moveUp</code> method moves a node to the <span class="emphasis"><em>previous</em></span> index in the <code class="computeroutput">childNodes</code> array.</p><p>It takes a single argument -- a reference to the node to be moved.</p><p>The following example moves the last <code class="computeroutput">&lt;cd&gt;</code> element to the second last position:</p><pre class="programlisting">//require the nodetools library
require_once('xml_domit_nodetools.php');

//move the node up
nodetools::moveUp($cdCollection-&gt;documentElement-&gt;lastChild);

//echo to browser
$cdCollection-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3720"></a>4.3.&nbsp;<code class="function">nodetools::moveDown</code></h3></div></div></div><p>The <code class="function">nodetools::moveDown</code> method moves a node to the <span class="emphasis"><em>next</em></span> index in the <code class="computeroutput">childNodes</code> array.</p><p>It takes a single argument -- a reference to the node to be moved.</p><p>The following example moves the first <code class="computeroutput">&lt;cd&gt;</code> element to the second position:</p><pre class="programlisting">//require the nodetools library
require_once('xml_domit_nodetools.php');

//move the node up
nodetools::moveDown($cdCollection-&gt;documentElement-&gt;firstChild);

//echo to browser
$cdCollection-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;cdlibrary&gt;
  &lt;cd discid="9b0ce70c"&gt;
    &lt;name&gt;Richard Thompson&lt;/name&gt;
    &lt;title&gt;Mock Tudor&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="bb0c3c0c"&gt;
    &lt;name&gt;Robbie Fulks&lt;/name&gt;
    &lt;title&gt;Couples in Trouble&lt;/title&gt;
  &lt;/cd&gt;
  &lt;cd discid="cf11720f"&gt;
    &lt;name&gt;Keller Williams&lt;/name&gt;
    &lt;title&gt;Laugh&lt;/title&gt;
  &lt;/cd&gt;
&lt;/cdlibrary&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3749"></a>4.4.&nbsp;<code class="function">nodetools::nodeExists</code></h3></div></div></div><p>The <code class="function">nodetools::nodeExists</code> method checks whether a node exists.on a given path. The path expression must conforming to the <code class="function">getElementsByPath</code> syntax.</p><p>The method takes two parameters -- a reference to the calling node (the node at which the search begins) and the path expression.</p><p>To check if the first child <code class="computeroutput">&lt;cd&gt;</code> element of the <code class="computeroutput">&lt;cdlibrary&gt;</code> element contains a <code class="computeroutput">&lt;title&gt;</code> element, you can do this:</p><pre class="programlisting">//require the nodetools library
require_once('xml_domit_nodetools.php');

//check if node exists
if (nodetools::nodeExists($cdCollection, '/cdlibrary/cd/title') {
  echo "Node exists!";
}
else {
  echo "Node does NOT exist";
}</pre><p>The result is:</p><pre class="programlisting">Node exists!</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3782"></a>4.5.&nbsp;<code class="function">nodetools::fromPath</code></h3></div></div></div><p>The <code class="function">nodetools::fromPath</code> method generates a heirarchy of elements based on a path expression.</p><p>It takes three parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>a reference to the DOMIT_Document that will create the elements</p></li><li><p>the path expression</p></li><li><p>the node value of a text node to be appended to the last element (if required)</p></li></ul></div><p>For example:</p><pre class="programlisting">//require the nodetools library
require_once('xml_domit_nodetools.php');

//build node tree
$myNodes =&amp; nodetools::fromPath($xmldoc, '/someElement/childElement', "Sample text");

//echo to browser
echo $myNodes-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;someElement&gt;
  &lt;childElement&gt;Sample text&lt;/childElement&gt;
&lt;/someElement&gt;</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e3813"></a>Chapter&nbsp;10.&nbsp;XML Namespaces</h2></div></div></div><p>The following chapter deals with XML namespaces. The <a href="http://www.w3.org/TR/REC-xml-names/" target="_top">XML Namespaces specification</a> defines a simple method for distinguishing XML and element and attribute names, by associating them with URI references (namespaces).</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e3821"></a>1.&nbsp;Introduction to XML Namespaces</h2></div></div></div><p>With the widespread adoption of XML, we have increasingly seen the coexistence and integration of different XML standards.</p><p>So what happens when you want to combine two XML documents, and each document contains an element named <code class="computeroutput">&lt;title&gt;</code>, but the <code class="computeroutput">&lt;title&gt;</code> element has a different meaning in each document? For example:</p><pre class="programlisting"><span class="bold"><strong>XML DOCUMENT #1:</strong></span>
&lt;?xml version="1.0"?&gt;
&lt;individual gender="m"&gt;
  &lt;name&gt;George Henry III&lt;/name&gt;
  &lt;title&gt;Duke of Fredericton&lt;/title&gt;
  &lt;books&gt;&lt;/books&gt;
&lt;/individual&gt;


<span class="bold"><strong>XML DOCUMENT #2:</strong></span>
&lt;?xml version="1.0"?&gt;
&lt;book&gt;
  &lt;title&gt;Transcendence Through XML&lt;/title&gt;
&lt;/book&gt;


<span class="bold"><strong>COMBINED DOCUMENT:</strong></span>
&lt;?xml version="1.0"?&gt;
&lt;individual gender="m"&gt;
  &lt;name&gt;George Henry III&lt;/name&gt;
  &lt;title&gt;Duke of Fredericton&lt;/title&gt;
  &lt;books&gt;
    &lt;book&gt;
      &lt;title&gt;Transcendence Through XML&lt;/title&gt;
    &lt;/book&gt;
  &lt;/books&gt;
&lt;/individual&gt;</pre><p>The potential problems here should be obvious. If, for instance, the <code class="function">getElementsByTagName</code> method was used to obtain a node list of elements with the a node name of "title", how would one differentiate between a person's title, and the title of a book?</p><p>Such naming collisions can cause confusion and error, and it is essential to have some means of differentiating between identically named, but contextually different, nodes.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3852"></a>1.1.&nbsp;URIs, Namespace Prefixes, and Namespace Declarations</h3></div></div></div><p>The XML Namespace specification proposes a mechanism whereby elements and attributes can be assigned <span class="emphasis"><em>namespaces</em></span> -- or, unique identifiers that allow one to differentiate between similar tag names.</p><p>The unique identifier comes in the form of a URI (Uniform Resource Identifier), which is a convention for identifying resources on the web (an URL, or universal resource locator, is a type of URI).</p><p>For example, the namespace URI for the <a href="http://dublincore.org/" target="_top">Dublin Core</a> -- an XML specification for interoperable online metadata standards -- is:</p><pre class="programlisting">http://purl.org/dc/elements/1.1/</pre><p>Since the URI tends to be somewhat longish to appear frequently in your document, you can specify an abbreviation for the URI, know as the <span class="emphasis"><em>Namespace Prefix</em></span>.</p><p>The namespace URI and namespace prefix are defined within your XML document, often at the level of the document element (but not necessarily so), using the keyword <span class="bold"><strong>xmlns</strong></span>.</p><p>In our <code class="computeroutput">&lt;individual&gt;</code> example from above, we might use namespaces to do the following:</p><pre class="programlisting">&lt;?xml version="1.0"?&gt;
&lt;person:individual person:gender="m"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/"&gt;
  &lt;person:name&gt;George Henry III&lt;/person:name&gt;
  &lt;person:title&gt;Duke of Fredericton&lt;/person:title&gt;
  &lt;person:books&gt;
    &lt;book:book&gt;
      &lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;
    &lt;/book:book&gt;
  &lt;/person:books&gt;
&lt;/person:individual&gt;</pre><p>You'll notice that in the document element node, two items have been added which appear to be attributes but which are actually <span class="emphasis"><em>Namespace Declarations</em></span>. A namespace declaration:</p><div class="itemizedlist"><ul type="disc"><li><p>begins with the prefix <code class="computeroutput">xmlns:</code></p></li><li><p>is followed by the namespace prefix: e.g., <code class="computeroutput">person</code></p></li><li><p>is followed by an equal sign</p></li><li><p>concludes with the URI in quotation marks: e.g. <code class="computeroutput">"http://www.engageinteractive.com/person/"</code></p></li></ul></div><p>The namespace declaration says basically that:</p><p><span class="emphasis"><em>There are elements and /or attributes in the following XML that will be assigned the URI <span class="bold"><strong>http://www.engageinteractive.com/person/</strong></span> and these elements and/or attributes are different from elements and/or attributes that are assigned the URI <span class="bold"><strong>http://www.engageinteractive.com/book/</strong></span> </em></span></p><p>It also says that:</p><p><span class="emphasis"><em>We will use the prefix "person" as shorthand for the URI <span class="bold"><strong>http://www.engageinteractive.com/person/</strong></span>, and we will use the abbreviation "book" as shorthand for the URI <span class="bold"><strong>http://www.engageinteractive.com/book/</strong></span> </em></span></p><p>It is then a simple task of placing the prefixes <span class="bold"><strong>person:</strong></span> and <span class="bold"><strong>book:</strong></span> before all corresponding elements and attributes. A namespace aware XML parser will be able to parse and differentiate between the elements named <code class="computeroutput">&lt;person:title&gt;</code> and <code class="computeroutput">&lt;book:title&gt;</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3947"></a>1.2.&nbsp;Default Namespace</h3></div></div></div><p>If an XML document does not contain a namespace declaration, then it is assumed that all elements in the document belong to the <span class="emphasis"><em>default namespace</em></span>. The default namespace is <span class="bold"><strong>null</strong></span> unless defined by the user.</p><p>If you would like to specify a user-defined default namespace, <span class="emphasis"><em>omit the namespace prefix in your xmlns declaration</em></span>:</p><pre class="programlisting">xmlns="http://www.engageinteractive.com/this.is.a.default.namespace"</pre><p><em><span class="remark">Note: Default namespaces do not apply to attributes.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3969"></a>1.3.&nbsp;Local Name</h3></div></div></div><p>When an XML document uses namespaces, the tag name of an element or attribute (i.e., the part following the namespace prefix) is referred to as its <span class="emphasis"><em>Local Name</em></span>.</p><p>The local name of the <code class="computeroutput">&lt;person:individual&gt;</code> element, for instance, is "individual".</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3982"></a>1.4.&nbsp;Qualified Name</h3></div></div></div><p>The concatenated namespace prefix and local name are referred to as the <span class="emphasis"><em>Qualified Name</em></span>, or <span class="emphasis"><em>qname</em></span>.</p><p>The qualified name of <code class="computeroutput">&lt;person:individual&gt;</code> element, for instance, is "person:individual"</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e3998"></a>1.5.&nbsp;DOM and XML Namespaces</h3></div></div></div><p>The DOM specifies a number of namespace aware methods, such as <code class="function">getElementsByTagNameNS</code>, which allows you to specify the qualified name of the element that you are searching for.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e4006"></a>2.&nbsp;DOMIT! and XML Namespaces</h2></div></div></div><p>DOMIT! (although not DOMIT! Lite) is compliant with the XML Namespace specification. It implements the following methods:</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4011"></a>2.1.&nbsp;<code class="function">setNamespaceAwareness</code></h3></div></div></div><p>To enable DOMIT! to process namespace data, invoke the <code class="function">setNamespaceAwareness</code> method before populating your XML document.</p><pre class="programlisting">$xmldoc-&gt;setNamespaceAwareness(true);</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4023"></a>2.2.&nbsp;<code class="function">declareNamespace</code></h3></div></div></div><p>The <code class="function">declareNamespace</code> method allows you to make a namespace declaration at the level of the calling element.</p><p>You must specify two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>a namespace prefix</p></li><li><p>a namespace URI</p></li></ul></div><p>The following creates a namespace declaration with a prefix of "domit" at the document element level:</p><pre class="programlisting">$xmldoc-&gt;documentElement-&gt;declareNamespace('domit', 'http://www.engageinteractive.com/domit/');</pre><p>The resulting namespace declaration would look like this:</p><pre class="programlisting">xmlns:domit="http://www.engageinteractive.com/domit/"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4051"></a>2.3.&nbsp;<code class="function">declareDefaultNamespace</code></h3></div></div></div><p>The <code class="function">declareDefaultNamespace</code> method allows you to make a default namespace declaration at the level of the calling element.</p><pre class="programlisting">$xmldoc-&gt;documentElement-&gt;declareDefaultNamespace('http://www.foo.com/a.default.namespace');</pre><p>The resulting ndefault amespace declaration would look like this:</p><pre class="programlisting">xmlns="http://www.foo.com/a.default.namespace"</pre><p>To reset the default namespace back to its original <span class="bold"><strong>null</strong></span> value, pass in an empty string to the <code class="function">declareDefaultNamespace</code> method:</p><pre class="programlisting">$xmldoc-&gt;documentElement-&gt;declareDefaultNamespace("");</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4079"></a>2.4.&nbsp;<code class="function">getNamespaceDeclarationsInScope</code></h3></div></div></div><p>The <code class="function">getNamespaceDeclarationsInScope</code> method returns an associative array of all namespace declarations that are in scope for the calling element.</p><pre class="programlisting">//acquire array of namespace declarations in scope
$nsMap = $xmldoc-&gt;documentElement-&gt;firstChild-&gt;getNamespaceDeclarationsInScope();

//echo to browser
print "&lt;pre&gt;";
print_r($nsMap);
print "&lt;/pre&gt;";</pre><p>The result is:</p><pre class="programlisting">Array
(
    [http://www.engageinteractive.com/person/] =&gt; person
    [http://www.engageinteractive.com/book/] =&gt; book
)</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4096"></a>2.5.&nbsp;<code class="function">getDefaultNamespaceDeclaration</code></h3></div></div></div><p>The <code class="function">getDefaultNamespaceDeclaration</code> method returns a string containing the default namespace declaration in scope for for the calling element.</p><pre class="programlisting">echo $xmldoc-&gt;documentElement-&gt;childNodes[2]-&gt;firstChild-&gt;getDefaultNamespaceDeclaration();</pre><p>The result is an empty string:</p><pre class="programlisting"></pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4112"></a>2.6.&nbsp;<code class="function">copyNamespaceDeclarationsLocally</code></h3></div></div></div><p>A common problem with namespaces occurs when an element is moved to another location in a document, or copied to another DOM document.</p><p>If the node being copied is not the document element, and the namespace declarations in scope for that element are declared higher up in the DOM tree (for example, in the document element), then the namespace declarations can be lost.</p><p>In the following XML, for instance, if the <code class="computeroutput">&lt;book:book&gt;</code> element were to be copied to another DOM document, the namespace declarations in the document element might not accompany the element:</p><pre class="programlisting"> &lt;?xml version="1.0"?&gt;
&lt;person:individual person:gender="m"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/"&gt;
  &lt;person:name&gt;George Henry III&lt;/person:name&gt;
  &lt;person:title&gt;Duke of Fredericton&lt;/person:title&gt;
  &lt;person:books&gt;
    &lt;book:book&gt;
      &lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;
    &lt;/book:book&gt;
  &lt;/person:books&gt;
&lt;/person:individual&gt;</pre><p>The <code class="function">copyNamespaceDeclarationsLocally</code> method addresses this problem, by forcing all namespace delarations that are in scope for the element to be explicitly duplicated on the element itself.</p><pre class="programlisting">//get reference to book:book node
$bookNode =&amp; $xmldoc-&gt;documentElement-&gt;childNodes[2]-&gt;firstChild;

//copy namespace declarations
$bookNode-&gt;copyNamespaceDeclarationsLocally();

//echo to browser
echo $bookNode-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;book:book xmlns:person="http://www.engageinteractive.com/person/" xmlns:book="http://www.engageinteractive.com/book/"&gt;
  &lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;
&lt;/book:book&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4141"></a>2.7.&nbsp;<code class="function">createElementNS</code></h3></div></div></div><p>The <code class="function">createElementNS</code> method is used to create a namespace compliant element.</p><p><code class="function">createElementNS</code> takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the element</p></li><li><p>its qualified name</p></li></ul></div><p>The following example will create the <code class="computeroutput">&lt;book:title&gt;</code> element:</p><pre class="programlisting">//create namespace compliant element
$myElement =&amp; $xmldoc-&gt;createElementNS('http://www.engageinteractive.com/book/', 'book:title');

//echo to browser
echo $myElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;book:title /&gt;</pre><p><em><span class="remark">Note that using the <code class="function">createElement</code> method will not create an element properly when namespace awareness is enabled.</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4180"></a>2.8.&nbsp;<code class="function">getElementsByTagNameNS</code></h3></div></div></div><p>The <code class="function">getElementsByTagNameNS</code> method is a namespace compliant version of <code class="function">getElementsByTagName</code>. It allows you to search for elements in an XML document by specifying:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the element</p></li><li><p>the local name</p></li></ul></div><p>The following example matches the <code class="computeroutput">&lt;book:title&gt;</code> element:</p><pre class="programlisting">//find book:title element
$myNodeList =&amp; $xmldoc-&gt;getElementsByTagNameNS('http://www.engageinteractive.com/book/', 'title');

//echo to browser
echo $myNodeList-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4212"></a>2.9.&nbsp;<code class="function">createAttributeNS</code></h3></div></div></div><p>The <code class="function">createAttributeNS</code> method is the namespace equivalent of <code class="function">createAttribute</code>. It enables you to create a new, namespace compliant, attribute node.</p><p><code class="function">createAttributeNS</code> takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the attribute</p></li><li><p>the local name</p></li></ul></div><p>The following example creates a new attribute named "book:language", with a value of "en"</p><pre class="programlisting">//create namespace compliant attribute
$myAttr =&amp; $xmldoc-&gt;createAttributeNS('http://www.engageinteractive.com/book/', 'language', 'en');

//echo to browser
echo $myAttr-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">book:language='en'</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4245"></a>2.10.&nbsp;<code class="function">hasAttributeNS</code> and <code class="function">getAttributeNS</code></h3></div></div></div><p>The <code class="function">hasAttributeNS</code> and <code class="function">getAttributeNS</code> methods are namespace compliant versions of <code class="function">hasAttribute</code> and <code class="function">getAttribute</code>. Both methods take as parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the attribute</p></li><li><p>the local name</p></li></ul></div><p>The following example checks if an attribute named 'gender' with a namespace URI of 'http://www.engageinteractive.com/person/' exists in the document element, and echoes the value to the browser:</p><pre class="programlisting">//set variables for namespace URI and local name
$URI = 'http://www.engageinteractive.com/person/';
$localName = 'gender';

//determine if atrribute exists
if ($xmldoc-&gt;documentElement-&gt;hasAttributeNS($URI, $localName)) {
  
  //echo to browser
  echo $xmldoc-&gt;documentElement-&gt;getAttributeNS($URI, $localName);
}</pre><p>The result is:</p><pre class="programlisting">m</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4283"></a>2.11.&nbsp;<code class="function">setAttributeNS</code></h3></div></div></div><p>The <code class="function">setAttributeNS</code> method is a namespace compliant version of <code class="function">setAttribute</code>. It creates a new namespace compliant attribute for the calling element, or overwrites the value of the attibute if one already exists.</p><p><code class="function">setAttributeNS</code> takes three parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the attribute</p></li><li><p>the qualified name</p></li><li><p>the value of the attribute</p></li></ul></div><p>The following example sets a new attribute on the &lt;book:title&gt; element.</p><pre class="programlisting">//find book:title element
$myNodeList =&amp; $xmldoc-&gt;getElementsByTagNameNS('http://www.engageinteractive.com/book/', 'title');

//get first match
$myElement =&amp; $myNodeList-&gt;item(0);

//add attribute named "book:language" to the element
$myElement-&gt;setAttributeNS('http://www.engageinteractive.com/book/', 'book:language', 'en');

//echo to browser
echo $myElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;book:title book:language="en"&gt;Transcendence Through XML&lt;/book:title&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4319"></a>2.12.&nbsp;<code class="function">getAttributeNodeNS</code> and <code class="function">setAttributeNodeNS</code></h3></div></div></div><p>The <code class="function">getAttributeNodeNS</code> and s<code class="function">etAttributeNodeNS</code> methods are namespace compliant versions of <code class="function">getAttributeNode</code> and <code class="function">setAttributeNode</code>.</p><p><code class="function">getAttributeNodeNS</code> takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the attribute</p></li><li><p>the local name</p></li></ul></div><p><code class="function">setAttributeNodeNS</code> takes a single parameter -- a reference to the node to be added/set.</p><p>The following example echoes the value of the "gender" attribute and then changes it to "f":</p><pre class="programlisting">//get the attribute node named "gender" in the document element
$attrNode =&amp; $xmldoc-&gt;documentElement-&gt;getAttributeNodeNS('http://www.engageinteractive.com/person/', 'gender');

//echo value of attr node
echo "original value of gender node is: " . $attrNode-&gt;getValue();

//create a new attribute node
$myAttr =&amp; $xmldoc-&gt;createAttributeNS('http://www.engageinteractive.com/person/', 'gender', 'f');

//overwrite existing attr with new one
$xmldoc-&gt;documentElement-&gt;setAttributeNodeNS();

//echo to browser
echo $xmldoc-&gt;documentElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;person:individual person:gender="f"
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/"&gt;
  &lt;person:name&gt;George Henry III&lt;/person:name&gt;
  &lt;person:title&gt;Duke of Fredericton&lt;/person:title&gt;
  &lt;person:books&gt;
    &lt;book:book&gt;
      &lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;
    &lt;/book:book&gt;
  &lt;/person:books&gt;
&lt;/person:individual&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4365"></a>2.13.&nbsp;<code class="function">removeAttributeNS</code></h3></div></div></div><p>The <code class="function">removeAttributeNS</code> method is the namespace counterpart to <code class="function">removeAttribute</code>. It enabled you to remove an attribute from an element.</p><p><code class="function">removeAttributeNS</code> takes two parameters:</p><div class="itemizedlist"><ul type="disc"><li><p>the namespace URI of the attribute</p></li><li><p>the local name</p></li></ul></div><p>The following example removes the "gender" attribute from the document element:</p><pre class="programlisting">//remove "gender" attribute from document element
$xmldoc-&gt;documentElement-&gt;removeAttributeNS('http://www.engageinteractive.com/person/', 'gender');

//echo to browser
echo $xmldoc-&gt;documentElement-&gt;toNormalizedString(true);</pre><p>The result is:</p><pre class="programlisting">&lt;person:individual
        xmlns:person="http://www.engageinteractive.com/person/"
        xmlns:book="http://www.engageinteractive.com/book/"&gt;
  &lt;person:name&gt;George Henry III&lt;/person:name&gt;
  &lt;person:title&gt;Duke of Fredericton&lt;/person:title&gt;
  &lt;person:books&gt;
    &lt;book:book&gt;
      &lt;book:title&gt;Transcendence Through XML&lt;/book:title&gt;
    &lt;/book:book&gt;
  &lt;/person:books&gt;
&lt;/person:individual&gt;</pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e4398"></a>Chapter&nbsp;11.&nbsp;XPath</h2></div></div></div><p>DOMIT! now has experimental <a href="http://www.w3.org/TR/xpath" target="_top">XPath</a> support.</p><p>XPath is a syntax for locating nodes in an XML tree using "path"-like expressions. A good introductory tutorial on XPath can be found at: <a href="http://www.w3schools.com/xpath/" target="_top">http://www.w3schools.com/xpath/</a></p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e4410"></a>1.&nbsp;XPath Overview</h2></div></div></div><p><em><span class="remark">Add content here!</span></em></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e4416"></a>2.&nbsp;<code class="function">selectNodes</code></h2></div></div></div><p>DOMIT! implements XPath calls through the <code class="function">selectNodes</code> method. Not all of the specification is supported currently.</p><p><code class="function">selectNodes</code> can be called from any XML document or element node. It converts an XPath expression into a node list or single node that matches the specified pattern. For example:</p><pre class="programlisting">$nodeList =&amp; $xmldoc-&gt;selectNodes("/book/chapter[@id='1234']");</pre><p>The above example will return a node list containing all nodes in the XML document:</p><div class="itemizedlist"><ul type="disc"><li><p>whose document element is named 'book', which has</p></li><li><p>a child node named 'chapter', which has</p></li><li><p>an 'id' attribute with a value of '1234'</p></li></ul></div><p>If you would like a single node to be returned by <code class="function">selectNodes</code>, rather than the entire node list of matching elements, you can specify the index of the requested node by passing an integer as the second parameter of <code class="function">selectNodes</code>.</p><p>The index is 1-based. The following example will return the first node matching the XPath expression:</p><pre class="programlisting">$nodeList =&amp; $xmldoc-&gt;selectNodes("/book/chapter[@id='1234']", 1);</pre><p><em><span class="remark">Add content here!</span></em></p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e4460"></a>Chapter&nbsp;12.&nbsp;DOMIT! Roadmap</h2></div></div></div><p>Some of the plans for DOMIT include:</p><div class="itemizedlist"><ul type="disc"><li><p>UTF-8 support</p></li><li><p>fuller XPath support</p></li><li><p>OneDOM: a generic wrapper for DOMIT! and the PHP DOM_XML library</p></li></ul></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e4475"></a>Chapter&nbsp;13.&nbsp;Contributing to DOMIT!</h2></div></div></div><p>DOMIT! has only been made possible through the suggestions, bug reports, and code submissions of others.</p><p>If you would like to contribute to DOMIT! or join the DOMIT! team, please email <code class="email">&lt;<a href="mailto:hide@address.com">hide@address.com</a>&gt;</code></p></div></div></body></html>
Return current item: ParamsProxy