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

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

<refnamediv>

<refname>DOMDocument::createElement</refname>

<refpurpose>Создаёт новый узел элемента</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>

Эта функция создаёт экземпляр класса

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

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Имя тега элемента.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Значение элемента. По умолчанию будет создан пустой элемент.

Значение также может быть установлено позднее путём присваивания при прямом обращении к свойству

<link linkend="domnode.props.nodevalue">DOMElement::$nodeValue</link>.

</para>

<para>

Значение будет установлено дословно, за исключением символов &lt; и &gt;, которые

будут экранированы. Обратите внимание, что символ &amp; нужно

экранировать самому, иначе он будет рассматриваться

как начало ссылки на сущность. Символ кавчек " также не будет экранирован.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Возвращает новый объект класса <classname>DOMElement</classname> или

&false; в случае возникновения ошибки.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Может выбросить исключение <exceptionname>DOMException</exceptionname>

со следующими кодами ошибок:

</simpara>

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Возникает, если параметр <parameter>localName</parameter> содержит недопустимые

символы.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>

Создание нового элемента и вставка его в качестве корневого

</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="xml">

</screen>

</example>

</para>

<para>

<example>

<title>Передача текста, содержащего неэкранированный &amp; в <parameter>value</parameter></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Значение <parameter>value</parameter> <emphasis>не</emphasis> будет

экранировано. Используйте функцию

<methodname>DOMDocument::createTextNode</methodname> для создания

текстового узла с <emphasis>поддержкой экранирования</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>