mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
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 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@188227 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour
parent
262e2e4dc7
commit
13156130e1
2 changed files with 200 additions and 52 deletions
|
|
@ -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>
|
||||
See also <function>domdocument_create_element_ns</function>, and
|
||||
<function>domnode_set_namespace</function>
|
||||
<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>
|
||||
<simplelist>
|
||||
<member><xref linkend="function.domdocument-create-element-ns" /></member>
|
||||
<member><xref linkend="function.domnode-set-namespace" /></member>
|
||||
</simplelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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>
|
||||
(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.
|
||||
</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 @@ $newnode->set_attribute("align", "left");
|
|||
]]>
|
||||
</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 @@ $newnode = $doc->append_child($node);
|
|||
]]>
|
||||
</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 @@ $newnode = $parent->append_child($element);
|
|||
$children = $newnode->children();
|
||||
$attr = $children[1]->set_attribute("align", "left");
|
||||
|
||||
echo "<pre>";
|
||||
$xmlfile = $dom->dump_mem();
|
||||
echo htmlentities($xmlfile);
|
||||
echo "</pre>";
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
The above example could also be done with
|
||||
<function>domnode_insert_before</function> instead of
|
||||
<function>domnode_append_child</function>.
|
||||
</para>
|
||||
<para>
|
||||
See also <function>domnode_insert_before</function>, and
|
||||
<function>domnode_clone_node</function>.
|
||||
The above example could also be done with
|
||||
<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>
|
||||
<simplelist>
|
||||
<member><xref linkend="function.domnode-insert-before" /></member>
|
||||
<member><xref linkend="function.domnode-clone-node" /></member>
|
||||
</simplelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
|
|
|||
Loading…
Reference in a new issue