registernodeclass.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="domdocument.registernodeclass" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>DOMDocument::registerNodeClass</refname>
  <refpurpose>Register extended class used to create base node type</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>DOMDocument::registerNodeClass</methodname>
   <methodparam><type>string</type><parameter>baseClass</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>null</type></type><parameter>extendedClass</parameter></methodparam>
  </methodsynopsis>

  <para>
   This method allows you to register your own extended DOM class to be used
   afterward by the PHP DOM extension.
  </para>
  <para>
   This method is not part of the DOM standard.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>baseClass</parameter></term>
     <listitem>
      <para>
       The DOM class that you want to extend. You can find a list of these 
       classes in the <link linkend="book.dom">chapter introduction</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>extendedClass</parameter></term>
     <listitem>
      <para>
       Your extended class name. If &null; is provided, any previously 
       registered class extending <parameter>baseClass</parameter> will
       be removed.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Adding a new method to DOMElement to ease our code</title>
    <programlisting role="php">
<![CDATA[
<?php

class myElement extends DOMElement {
   function appendElement($name) { 
      return $this->appendChild(new myElement($name));
   }
}

class myDocument extends DOMDocument {
   function setRoot($name) { 
      return $this->appendChild(new myElement($name));
   }
}

$doc = new myDocument();
$doc->registerNodeClass('DOMElement', 'myElement');

// From now on, adding an element to another costs only one method call ! 
$root = $doc->setRoot('root');
$child = $root->appendElement('child');
$child->setAttribute('foo', 'bar');

echo $doc->saveXML();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="xml">
<![CDATA[
<?xml version="1.0"?>
<root><child foo="bar"/></root>
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Retrieving elements as custom class</title>
    <programlisting role="php">
<![CDATA[
<?php
class myElement extends DOMElement {
    public function __toString() {
        return $this->nodeValue;
    }
}

$doc = new DOMDocument;
$doc->loadXML("<root><element><child>text in child</child></element></root>");
$doc->registerNodeClass("DOMElement", "myElement");

$element = $doc->getElementsByTagName("child")->item(0);
var_dump(get_class($element));

// And take advantage of the __toString method..
echo $element;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="xml">
<![CDATA[
string(9) "myElement"
text in child
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Retrieving owner document</title>
    <para>
     When instantiating a custom <classname>DOMDocument</classname> the
     <varname>ownerDocument</varname> property will refer to the instantiated
     class, meaning there is no need (and in fact not possible) to use
     <function>DOMDocument::registerNodeClass</function> with
     <classname>DOMDocument</classname>
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class myDOMDocument extends DOMDocument {
}

class myOtherDOMDocument extends DOMDocument {
}

// Create myDOMDocument with some XML
$doc = new myDOMDocument;
$doc->loadXML("<root><element><child>text in child</child></element></root>");

$child = $doc->getElementsByTagName("child")->item(0);

// The current owner of the node is myDOMDocument
var_dump(get_class($child->ownerDocument));

// Import a node from myDOMDocument
$newdoc = new myOtherDOMDocument;
$child = $newdoc->importNode($child);

// The new owner of the node has changed to myOtherDOMDocument
var_dump(get_class($child->ownerDocument));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="xml">
<![CDATA[
string(13) "myDOMDocument"
string(18) "myOtherDOMDocument"
]]>
    </screen>
   </example>
  </para>
  <para>
   <example xml:id="domdocument.registernodeclass.example.transient">
    <title>Custom objects are transient</title>
    <caution>
     <simpara>
      Objects of the registered node classes are transient, i.e. they are
      destroyed when they are no longer referenced from PHP code, and recreated
      when being retrieved again. That implies that custom property values will be
      lost after recreation.
     </simpara>
    </caution>
    <programlisting role="php">
<![CDATA[
<?php
class MyDOMElement extends DOMElement
{
    public $myProp = 'default value';
}

$doc = new DOMDocument();
$doc->registerNodeClass('DOMElement', 'MyDOMElement');

$node = $doc->createElement('a');
$node->myProp = 'modified value';
$doc->appendChild($node);

echo $doc->childNodes[0]->myProp, PHP_EOL;
unset($node);
echo $doc->childNodes[0]->myProp, PHP_EOL;
?>]]>
    </programlisting>
    &example.outputs;
    <screen role="xml">
<![CDATA[
modified value
default value
]]>
    </screen>
   </example>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->