<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="domdocument.createelement" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>DOMDocument::createElement</refname>

<refpurpose>Crea un nuevo nodo elemento</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="DOMDocument">

<modifier>public</modifier> <type class="union"><type>DOMElement</type><type>false</type></type><methodname>DOMDocument::createElement</methodname>

<methodparam><type>string</type><parameter>localName</parameter></methodparam>

<methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>

</methodsynopsis>

<para>

Esta función crea una nueva instancia de la clase

<classname>DOMElement</classname>. &dom.node.inserted;

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>localName</parameter></term>

<listitem>

<para>

El nombre de etiqueta del elemento.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>value</parameter></term>

<listitem>

<para>

El valor del elemento. De manera predeterminada se creará un elemento vacio.

El valor también puede ser asignado más tarde con <link linkend="domnode.props.nodevalue">DOMElement::$nodeValue</link>.

</para>

<para>

El valor es usado al pie de la letra, excepto que las referencias de entidad

&lt; y &gt; se escaparán. Tenga en cuenta que &amp; tiene que ser escapado manualmente;

de lo contrario, se tomará como inicio de una referencia de entidad. Además "

no sera escapado.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve una nueva instanca de la clase <classname>DOMElement</classname> o &false;

si ha ocurrido un error.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Puede lanzar una <exceptionname>DOMException</exceptionname> con los

siguientes códigos de error:

</simpara>

<para>

<variablelist>

<varlistentry>

<term><constant>DOM_INVALID_CHARACTER_ERR</constant></term>

<listitem>

<para>

Lanzado si <parameter>localName</parameter> contiene un carácter inválido.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Crear un nuevo elemento e insertarlo como raíz</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="xml">

</screen>

</example>

</para>

<para>

<example>

<title>Pasando texto que contiene un &amp; sin escapar como <parameter>valor</parameter></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

El parámetro <parameter>value</parameter> <emphasis>no</emphasis> será escapado.

Utilice <methodname>DOMDocument::createTextNode</methodname> para crear un

nodo de texto con <emphasis>soporte para escape de caracteres</emphasis>.

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><methodname>DOMNode::appendChild</methodname></member>

<member><methodname>DOMDocument::createAttribute</methodname></member>

<member><methodname>DOMDocument::createAttributeNS</methodname></member>

<member><methodname>DOMDocument::createCDATASection</methodname></member>

<member><methodname>DOMDocument::createComment</methodname></member>

<member><methodname>DOMDocument::createDocumentFragment</methodname></member>

<member><methodname>DOMDocument::createElementNS</methodname></member>

<member><methodname>DOMDocument::createEntityReference</methodname></member>

<member><methodname>DOMDocument::createProcessingInstruction</methodname></member>

<member><methodname>DOMDocument::createTextNode</methodname></member>

</simplelist>

</para>

</refsect1>

</refentry>