cvs: phpdoc /en/functions domxml.xml

steinm Mon Apr 15 11:18:11 2002 EDT Modified files: /phpdoc/en/functions domxml.xml Log: - documentation for DomNode->append_sibling() and DomNode->remove_child(). - Diskussion of old and new behaviour of DomNode->append_child() Index: phpdoc/en/functions/domxml.xml diff -u phpdoc/en/functions/domxml.xml:1.40 phpdoc/en/functions/domxml.xml:1.41 --- phpdoc/en/functions/domxml.xml:1.40 Fri Apr 12 09:23:04 2002 +++ phpdoc/en/functions/domxml.xml Mon Apr 15 11:18:08 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.40 $ --> +<!-- $Revision: 1.41 $ --> <reference id="ref.domxml"> <title>DOM XML functions</title> <titleabbrev>DOM XML</titleabbrev> @@ -42,6 +42,14 @@ <sect1 id="domxml-deprecated"> <title>Deprecated functions</title> <para> + There a quite some functions which do not fit into the DOM standard and + should not be used anymore as listed a in the following table. + The function <function>DomNode_append_child</function> has changed its + behaviour. In now actually adds a child and not a sibling. If this + breaks your application use the non DOM function + <function>DomNode_append_sibling</function>. + </para> + <para> <table> <title>Deprecated functions and its replacements</title> <tgroup cols="2"> @@ -544,10 +552,19 @@ <entry></entry> </row> <row> + <entry><function>DomNode_append_sibling</function></entry> + <entry>Not in DOM standard. This function emulates the former + behaviour of <function>DomNode_append_child</function>.</entry> + </row> + <row> <entry><function>DomNode_remove_child</function></entry> <entry></entry> </row> <row> + <entry><function>DomNode_replace_child</function></entry> + <entry></entry> + </row> + <row> <entry><function>DomNode_has_child_nodes</function></entry> <entry></entry> </row> @@ -2285,6 +2302,44 @@ </refsect1> </refentry> + <refentry id='function.DomNode-append-sibling'> + <refnamediv> + <refname>DomNode->append_sibling</refname> + <refpurpose> + Adds new sibling to a node + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>object</type><methodname>DomNode->append_sibling</methodname> + <methodparam><type>object</type><parameter>newnode</parameter></methodparam> + </methodsynopsis> + <para> + This functions appends a sibling to an existing node. + The child can be created with e.g. + <function>DomDocument_create_element</function>, + <function>DomDocument_create_text</function> etc. or simply by using any + other node. + </para> + <para> + Before a new sibling is added it is first duplicated. Therefore the new + child is a completely new copy which can be modified without changing the + node which was passed to this function. If the node passed has children + itself, they will be duplicated as well, which makes it quite easy to + duplicate large parts of a xml document. The return value is the + added sibling. If you plan to do further modifications on the added + sibling you must use the returned node. + </para> + <para> + This function has been added to provide the behaviour of + <function>DomNode_append_child</function> as it works till PHP 4.2. + <para> + See also <function>DomNode_append_before</function>. + </para> + </refsect1> + </refentry> + <refentry id='function.DomNode-remove-child'> <refnamediv> <refname>DomNode->remove_child</refname> @@ -2299,9 +2354,62 @@ <methodparam><type>object</type><parameter>oldchild</parameter></methodparam> </methodsynopsis> <para> - This functions removes a child from a list of children. If child cannot + This functions removes a child from a list of children. If the child cannot be removed or is not a child the function will return false. - If the child could be removed the functions returns the old child. + If the child could be removed the function returns the old child. + </para> + <para> + <example> + <title>Removing a child</title> + <programlisting role="php"> +<![CDATA[ +<?php +include("example.inc"); + +if(!$dom = domxml_open_mem($xmlstr)) { + echo "Error while parsing the document\n"; + exit; +} + +$elements = $dom->get_elements_by_tagname("tbody"); +$element = $elements[0]; +$children = $element->child_nodes(); +$child = $element->remove_child($children[0]); + +echo "<PRE>"; +$xmlfile = $dom->dump_mem(true); +echo htmlentities($xmlfile); +echo "</PRE>"; +?> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>DomNode_append_child</function>. + </para> + </refsect1> + </refentry> + + <refentry id='function.DomNode-replace-child'> + <refnamediv> + <refname>DomNode->replace_child</refname> + <refpurpose> + Replaces child from list of children + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>object</type><methodname>DomNode->replace_child</methodname> + <methodparam><type>object</type><parameter>oldchild</parameter></methodparam> + <methodparam><type>object</type><parameter>newchild</parameter></methodparam> + </methodsynopsis> + <para> + This functions replace a child from a list of children. If the child cannot + be replaced or the old child cannot be found the function will return + false. + If the child could be replaced the function returns the old child. </para> <para> <example>