Стандартный тип поля Joomla XML - Textarea

Стандартный тип поля XML-форм Joomla — Textarea рендерит нативный HTML-элемент <textarea> для ввода многострочного текста без визуального редактора. Поле предназначено для работы с обычным текстом (plain text), поддерживает фильтрацию (filter), валидацию (validate) и условное отображение (showon).

Joomla 3.x Joomla 4.x Joomla 5.x Joomla 6.x

Атрибуты поля

Ниже приведены основные атрибуты, поддерживаемые типом поля . Используйте их внутри тега <field> вашего XML-манифеста.

Атрибут	Тип	Описание
`name`	string	Обязательно. Уникальный системный идентификатор поля. Используется для получения значения в PHP ($input->get('name')).
`type`	string	Обязательно. Должно быть равно "textarea". Определяет тип поля и его поведение (многострочное текстовое поле).
`label`	string	Заголовок поля, видимый пользователю в админке. Может быть языковой константой (например, COM_EXAMPLE_NOTES_LABEL).
`filter`	string	Метод фильтрации данных перед сохранением. Для textarea критично: string (очистка), safehtml (безопасный HTML), raw (без обработки). По умолчанию зависит от глобальных настроек.
`description`	string	Текст подсказки. В Joomla 3 отображается при наведении на заголовок (tooltip), в J4/5/6 может выводиться под полем или во всплывающем окне.
`rows`	integer	Количество видимых строк текстовой области. Если не указано, браузер использует значение по умолчанию (обычно 2-3 строки).
`cols`	integer	Видимая ширина поля в символах. Если не указано, браузер автоматически определяет ширину на основе CSS или родительского контейнера.
`hint`	string	Текст-заполнитель (placeholder), отображаемый внутри поля до ввода данных. В Joomla 4+ заменяет устаревший подход с description для подсказок ввода.
`default`	string	Значение по умолчанию при создании новой записи. Может быть языковой константой или статическим текстом.
`class`	string	CSS-классы для стилизации самого поля textarea. Например, class="form-control my-custom-class".
`required`	boolean	Делает поле обязательным для заполнения (true/false). Активирует валидацию на клиенте (HTML5) и сервере.
`validate`	string	Тип валидации данных: text, maxLength, customRule. Работает совместно с filter для комплексной проверки.
`readonly`	boolean	Блокирует редактирование поля, но значение отправляется на сервер при сохранении формы (true/false).
`disabled`	boolean	Полностью отключает поле: оно не редактируется и не отправляется на сервер (true/false).
`maxlength`	integer	Максимальное количество символов, которое можно ввести (HTML5). Рекомендуется дублировать проверкой в БД и validate="maxLength".
`showon`	string	Условное отображение поля в зависимости от значений других полей. Например, showon="show_notes:1" (показывать, если поле show_notes равно 1).
`onchange`	string	JavaScript-код, выполняемый при изменении значения поля. Например, onchange="myFunction(this.value)".
`wrap`	string	Поведение переноса строк при отправке формы: soft (по умолчанию, переносы не добавляются), hard (добавляются \r\n), off (переносы отключены).
`labelClass`	string	CSS-классы для обёртки подписи (label). Например, labelClass="control-label".
`minlength`	integer	Минимальное количество символов (HTML5). Работает совместно с required для строгой валидации ввода.
`autocomplete`	string	Управление автозаполнением браузера: on, off, или специфичные токены (username, email и т.д.).
`spellcheck`	boolean	Включение проверки орфографии браузером: true (включено), false (отключено).
`onkeyup`	string	JavaScript-код, выполняемый при отпускании клавиши в поле.
`onkeydown`	string	JavaScript-код, выполняемый при нажатии клавиши в поле.

Визуальные примеры

Ниже представлены скриншоты отображения поля в разных версиях Joomla и темах административной панели.

Joomla 3 Isis

Поле типа Textarea в настройках Joomla 3.x (шаблон админки Isis)

Классический вид поля в шаблоне Isis.

Joomla 4 / 5 / 6 Cassiopeia (Светлая)

Визуальное отображение поля Textarea в Joomla 4/5/6 - светлая тема админки Cassiopeia

Современный дизайн Cassiopeia. Светлая тема.

Joomla 4 / 5 / 6 Cassiopeia (Темная)

Визуальное отображение поля Textarea в Joomla 4/5/6 - темная тема админки Cassiopeia

Темная тема админки. Контрастный текст и темный фон.

Пример использования в XML

Добавьте этот код внутрь тега формы вашего XML-манифеста. Атрибут type="textarea" создаёт стандартное многострочное поле ввода, сохраняющее переносы строк и поддерживающее фильтрацию данных через параметр filter.

<field
    name="notes"
    type="textarea"
    label="Примечания"
    description="Введите дополнительную информацию в несколько строк."/>

Получение значения в PHP

Пример получения и обработки значения поля textarea в PHP-коде вашего компонента. Обратите внимание: метод getString() автоматически применяет базовую фильтрацию, но для контента с разметкой рекомендуется явно указывать filter="safehtml" в XML. При выводе не забывайте обрабатывать переносы строк через nl2br() или CSS-свойство white-space: pre-wrap.

// --- ВАРИАНТ ДЛЯ JOOMLA 4 / 5 / 6 (Современный) ---
use Joomla\CMS\Factory;

// Получаем объект ввода через Factory (рекомендуемый способ в MVC)
$input = Factory::getApplication()->input;

// getString() автоматически экранирует опасные символы и обрезает переносы при необходимости
// Второй параметр — значение по умолчанию, если поле пустое
$myText = $input->getString('notes', '');

// Альтернатива: если нужен контроль фильтра вручную
// Доступные фильтры: 'raw' (без обработки), 'string' (базовая очистка), 'safehtml' (разрешён безопасный HTML)
$myText = $input->get('notes', '', 'safehtml');


// --- ВАРИАНТ ДЛЯ JOOMLA 3.x (Устаревший) ---
// В J3 использовался JFactory или JRequest
$input = JFactory::getApplication()->input;
$myText = $input->get('notes', '', 'string'); 

// ИЛИ старым способом (не рекомендуется, но может встречаться в легаси-коде):
$myText = JRequest::getVar('notes', '', 'default', 'string');


// --- ОБРАБОТКА ПЕРЕНОСОВ СТРОК И ВЫВОД ---
// Текст из textarea сохраняет переносы строк (\n). 
// Для корректного отображения в HTML используйте nl2br() или CSS white-space.

// Вариант 1: Преобразовать переносы в <br>
echo nl2br(htmlspecialchars($myText, ENT_QUOTES, 'UTF-8'));

// Вариант 2: Использовать CSS (рекомендуется для современного фронтенда)
echo '<div style="white-space: pre-wrap;">'.htmlspecialchars($myText, ENT_QUOTES, 'UTF-8').'</div>';

// Вариант 3: Если в поле разрешён безопасный HTML (filter="safehtml")
// Используем Joomla\Filter\OutputFilter для дополнительной защиты
use Joomla\Filter\OutputFilter;
echo OutputFilter::safeHtml($myText); // Только для J4+, в J3: JFilterOutput::safeHtml()


// --- ВАЖНО: ВЫБОР ФИЛЬТРА В ЗАВИСИМОСТИ ОТ СЦЕНАРИЯ ---
/*
| Фильтр      | Когда использовать                          | Безопасность          |
|-------------|---------------------------------------------|-----------------------|
| 'string'    | Обычный текст, комментарии, описания        | ✅ Автоматическая очистка |
| 'safehtml'  | Текст с допустимыми тегами (<b>, <i>, <a>)  | ✅ Фильтрация опасных тегов |
| 'raw'       | Только если вы сами обрабатываете контент   | ⚠️ Требует ручной санитизации |
| 'html'      | Не рекомендуется без кастомной валидации    | ❌ Может пропустить XSS |
*/

// --- БОНУС: Получение значения из модели/формы (если работаете внутри компонента) ---
// В современном подходе (J4+) данные формы часто доступны через $this->getItem() или $form->getValue()
// Пример в модели или представлении:
$myText = $this->item->notes ?? ''; 
// Или через форму:
$myText = $form->getValue('notes');

После получения данных важно помнить, что атрибут filter в XML очищает ввод, но не заменяет экранирование при выводе, всегда оборачивайте результат в htmlspecialchars() для защиты от XSS. Так как поле сохраняет символы переноса строк, для корректного отображения в HTML используйте nl2br() или CSS-свойство white-space: pre-wrap. Выбор фильтра зависит от сценария: string оптимален для обычного текста, safehtml разрешает безопасную разметку, а raw следует применять только при программной обработке. Приведённый код использует современное пространство имён Joomla 4–6; для обратной совместимости с Joomla 3.x достаточно заменить Joomla\CMS\Factory на JFactory.

Совет: Всегда явно указывайте атрибут filter (string для чистого текста или safehtml для допустимой разметки) — без него Joomla не гарантирует автоматическую защиту от XSS. При выводе данных обязательно используйте htmlspecialchars() и обрабатывайте переносы строк через nl2br() или CSS white-space: pre-wrap. В Joomla 4+ для текста-заполнителя внутри поля используйте hint, так как description теперь рендерится исключительно как всплывающая подсказка рядом с полем.

Подводные камни

Отсутствие явного фильтра: Без указания атрибута filter применяется системный фильтр по умолчанию, поведение которого различается в версиях (J3 оставляет больше свободы, J4/J5/J6 строже). Это может неожиданно вырезать допустимые теги или оставить XSS-уязвимость, если вывод не экранируется отдельно.
Игнорирование переносов строк в HTML: Символы \n из формы не преобразуются в
автоматически. Без обработки через nl2br() или CSS white-space: pre-wrap многострочный текст отобразится сплошной строкой на фронтенде.
Небезопасный default с переносами: Вставка реальных символов новой строки в атрибут default нарушит валидность XML-манифеста. Используйте HTML-сущности или задавайте значение по умолчанию через PHP/базу данных.
Путаница между description и hint: В Joomla 3 description выводился как статический текст под полем, в J4+ он перемещён во всплывающую подсказку (tooltip). Для placeholder внутри поля в современных версиях обязательно используйте hint.
Клиентский maxlength и ошибки БД: Атрибут maxlength ограничивает ввод только на стороне браузера (HTML5). Если сохранённый текст превысит лимит столбца VARCHAR/TEXT в базе данных, запрос завершится ошибкой SQL. Всегда синхронизируйте maxlength и схему БД.
Потеря данных в динамических субформах: В компонентах subform или repeatable значения textarea могут сбрасываться при программном клонировании блоков из-за особенностей JS-рендеринга в J4+. Требуется явная проверка поведения в целевой версии и корректная привязка атрибута name.
Конфликт с визуальным редактором: Поле textarea не загружает WYSIWYG. Если в проекте ожидается форматирование текста пользователями, необходимо заменить тип на editor или явно указать это в ТЗ, иначе контент будет сохраняться как plain-text.