didou Sun Jun 12 15:07:02 2005 EDT
Modified files:
/phpdoc/en/reference/domxml/functions DomNode-append-child.xml
DomNode-add-namespace.xml
Log:
Switched DOMNode->append_child() and DOMNode->add_namespace() to the new
structure
Added another changelog for append_child
Added a refsect1 named migration describing how to jump from domxml to dom
Added user comments
http://cvs.php.net/diff.php/phpdoc/en/reference/domxml/functions/DomNode-append-child.xml?r1=1.13&r2=1.14&ty=u
Index: phpdoc/en/reference/domxml/functions/DomNode-append-child.xml
diff -u phpdoc/en/reference/domxml/functions/DomNode-append-child.xml:1.13
phpdoc/en/reference/domxml/functions/DomNode-append-child.xml:1.14
--- phpdoc/en/reference/domxml/functions/DomNode-append-child.xml:1.13 Sun Jun
12 00:42:09 2005
+++ phpdoc/en/reference/domxml/functions/DomNode-append-child.xml Sun Jun
12 15:07:02 2005
@@ -1,49 +1,119 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
<refentry id='function.domnode-append-child'>
<refnamediv>
<refname>DomNode->append_child</refname>
<refpurpose>
- Adds new child at the end of the children
+ Adds a new child at the end of the children
</refpurpose>
</refnamediv>
- <refsect1>
+ <refsect1 role="description">
&reftitle.description;
- <methodsynopsis>
- <type>domelement</type><methodname>DomNode->append_child</methodname>
-
<methodparam><type>domelement</type><parameter>newnode</parameter></methodparam>
- </methodsynopsis>
+ <classsynopsis>
+ <ooclass><classname>DOMNode</classname></ooclass>
+ <methodsynopsis>
+ <type>DOMNode</type><methodname>append_child</methodname>
+
<methodparam><type>DOMNode</type><parameter>newnode</parameter></methodparam>
+ </methodsynopsis>
+ </classsynopsis>
<para>
This functions appends a child to an existing list of children or creates
- a new list of children. 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>
- (PHP < 4.3) Before a new child is appended 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 an XML document. The return value is the
- appended child. If you plan to do further modifications on the appended
- child you must use the returned node.
- </para>
- <para>
- (PHP 4.3.0/4.3.1) The new child <parameter>newnode</parameter> is first
- unlinked from its existing context, if it's already a child of DomNode.
- Therefore the node is moved and not copies anymore.
- </para>
- <para>
- (PHP >= 4.3.2) The new child <parameter>newnode</parameter> is first
- unlinked from its existing context, if it's already in the tree. Therefore
- the node is moved and not copied. This is the behaviour according to the
- W3C specifications. If you want to duplicate large parts of an XML document,
- use DomNode->clone_node() before appending.
+ a new list of children.
+ </para>
+ </refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>newnode</parameter></term>
+ <listitem>
+ <para>
+ The node being appended. It can be created with e.g.
+ <xref linkend="function.domdocument-create-element" />,
+ <xref linkend="function.domdocument-create-text-node" /> etc. or
+ simply by using any other node.
+ </para>
+ <note>
+ <para>
+ You can not append a <classname>DOMAttribute</classname> using this
+ method. Use <xref linkend="function.domelement-set-attribute" />
+ instead.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns the appended node on success or &false; on failure.
+ </para>
+ </refsect1>
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>4.3.0</entry>
+ <entry>
+ You are not allowed anymore to insert a node from another document.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.0</entry>
+ <entry>
+ Prior to PHP 4.3.0, the new child is duplicated before being
+ appended.
+ 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 an XML
+ document. The return value is the appended child. If you plan to do
+ further modifications on the appended child you must use the returned
+ node.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.0 and 4.3.1</entry>
+ <entry>
+ The new child <parameter>newnode</parameter> is first unlinked from
+ its existing context, if it's already a child of DomNode. Therefore
+ the <parameter>newnode</parameter> is moved and not copies anymore.
+ This is the behaviour according to the W3C specifications. If you
+ need the old behaviour, use <xref
+ linkend="function.domnode-clone-node" /> before appending.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.2</entry>
+ <entry>
+ The new child <parameter>newnode</parameter> is first unlinked from
+ its existing context, if it's already in the tree. Same rules apply.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ The following example adds a new element node to a fresh document and sets
+ the attribute <literal>align</literal> to <literal>left</literal>.
</para>
<para>
- The following example will add a new element node to a fresh document
- and sets the attribute "align" to "left".
<example>
<title>Adding a child</title>
<programlisting role="php">
@@ -57,7 +127,11 @@
]]>
</programlisting>
</example>
+ </para>
+ <para>
The above example could also be written as the following:
+ </para>
+ <para>
<example>
<title>Adding a child</title>
<programlisting role="php">
@@ -71,10 +145,14 @@
]]>
</programlisting>
</example>
+ </para>
+ <para>
A more complex example is the one below. It first searches for a certain
element, duplicates it including its children and adds it as a sibling.
- Finally a new attribute is added to one of the children of the new
- sibling and the whole document is dumped.
+ Finally a new attribute is added to one of the children of the new sibling
+ and the whole document is dumped.
+ </para>
+ <para>
<example>
<title>Adding a child</title>
<programlisting role="php">
@@ -96,21 +174,32 @@
$children = $newnode->children();
$attr = $children[1]->set_attribute("align", "left");
-echo "<pre>";
$xmlfile = $dom->dump_mem();
echo htmlentities($xmlfile);
-echo "</pre>";
?>
]]>
</programlisting>
</example>
+ </para>
+ <para>
The above example could also be done with
- <function>domnode_insert_before</function> instead of
- <function>domnode_append_child</function>.
+ <xref linkend="function.domnode-insert-before" /> instead of
+ <xref linkend="function.domnode-append-child" />.
+ </para>
+ </refsect1>
+ <refsect1 role="migration">
+ <title>Migrating to PHP 5</title>
+ <para>
+ You should use <xref linkend='function.dom-domnode-appendchild' />.
</para>
+ </refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>domnode_insert_before</function>, and
- <function>domnode_clone_node</function>.
+ <simplelist>
+ <member><xref linkend="function.domnode-insert-before" /></member>
+ <member><xref linkend="function.domnode-clone-node" /></member>
+ </simplelist>
</para>
</refsect1>
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml?r1=1.7&r2=1.8&ty=u
Index: phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml
diff -u phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml:1.7
phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml:1.8
--- phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml:1.7 Sun Jun
12 00:42:09 2005
+++ phpdoc/en/reference/domxml/functions/DomNode-add-namespace.xml Sun Jun
12 15:07:02 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
<refentry id='function.domnode-add-namespace'>
<refnamediv>
<refname>DomNode->add_namespace</refname>
@@ -7,18 +7,77 @@
Adds a namespace declaration to a node
</refpurpose>
</refnamediv>
- <refsect1>
+ <refsect1 role="description">
&reftitle.description;
- <methodsynopsis>
- <type>bool</type><methodname>DomNode->add_namespace</methodname>
- <methodparam><type>string</type><parameter>uri</parameter></methodparam>
- <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
- </methodsynopsis>
+ <classsynopsis>
+ <ooclass><classname>DOMNode</classname></ooclass>
+ <methodsynopsis>
+ <type>bool</type><methodname>add_namespace</methodname>
+ <methodparam><type>string</type><parameter>uri</parameter></methodparam>
+ <methodparam
choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
+ </methodsynopsis>
+ </classsynopsis>
<para>
+ This method adds a namespace declaration to a node.
</para>
+ <note>
+ <para>
+ This method is not part of the DOM specification.
+ </para>
+ </note>
+ </refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>uri</parameter></term>
+ <listitem>
+ <para>
+ The namespace URI of the node.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>prefix</parameter></term>
+ <listitem>
+ <para>
+ The namespace prefix of the node. If not set, a random prefix will be
+ generated.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.success;
+ </para>
+ </refsect1>
+ <refsect1 role="migration">
+ <title>Migrating to PHP 5</title>
+ <para>
+ You can set the namespace URI and prefix of a
<classname>DOMElement</classname>
+ or a <classname>DOMAttr</classname> at creation time by using
+ <xref linkend='function.dom-domdocument-createelementns' /> or
+ <xref linkend='function.dom-domdocument-createattributens' />.
+ </para>
+ <note>
+ <para>
+ Remember the an attribute does not inherit its namespace from the element
+ it is attached to.
+ </para>
+ </note>
+ </refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
- See also <function>domdocument_create_element_ns</function>, and
- <function>domnode_set_namespace</function>
+ <simplelist>
+ <member><xref linkend="function.domdocument-create-element-ns" /></member>
+ <member><xref linkend="function.domnode-set-namespace" /></member>
+ </simplelist>
</para>
</refsect1>
</refentry>
