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

Стандартное поле Joomla XML типа number основано на HTML5-элементе <input type="number"> и отображает поле ввода с кнопками увеличения и уменьшения значения. Оно предназначено для ввода чисел, поддерживает настройку диапазона и шага изменения (через атрибуты min, max, step) и имеет встроенную проверку формата данных. Поле корректно работает во всех актуальных версиях Joomla, включая поддерживаемую ветку 3.x, а также версии 4, 5 и 6.

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

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

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

Атрибут	Тип	Описание
`name`	string	Обязательно. Уникальный системный идентификатор поля. Используется для сохранения данных и получения значения в PHP ($input->get('name')).
`type`	string	Обязательно. Должно быть равно "number". Определяет тип поля как числовое input-поле HTML5.
`label`	string	Заголовок поля, видимый пользователю в админке или на сайте. Может быть языковой константой (например, COM_EXAMPLE_NUMBER_LABEL).
`description`	string	Текст подсказки. В Joomla 3 отображается при наведении на заголовок (tooltip), в J4/5/6 — может выводиться под полем или во всплывающем окне.
`default`	int / float	Значение по умолчанию. Устанавливает начальное число в поле, если оно пустое или новое.
`min`	int / float	Минимально допустимое значение. Браузер не позволит отправить форму, если введенное число меньше этого значения.
`max`	int / float	Максимально допустимое значение. Ограничивает верхнюю границу ввода числа.
`step`	int / float / any	Шаг изменения значения при использовании стрелок. По умолчанию 1 (целые числа). Для дробных укажите 0.01 или any.
`required`	bool	Делает поле обязательным для заполнения. Если true, браузер заблокирует отправку формы при пустом поле.
`readonly`	bool	Блокирует редактирование. Пользователь видит значение, но не может его изменить. Данные отправляются на сервер.
`filter`	string	Фильтр данных для PHP. Рекомендуется явно указывать "int" (целые) или "float" (дробные) для безопасности типов.
`class`	string	Дополнительные CSS-классы для тега . Позволяет кастомизировать внешний вид через стили.
`hint`	string	Текст-подсказка (placeholder) внутри пустого поля. Исчезает при начале ввода. Не путать с description.
`showon`	string	Условие отображения поля. Поле появится только если другое поле имеет определенное значение (например, showon="other_field:1").
`disabled`	bool	Отключает поле. Оно становится серым и не отправляется на сервер при сохранении формы.
`autocomplete`	string	Управление автозаполнением браузера. Используйте "off" для отключения подсказок предыдущих значений.
`autofocus`	bool	Автоматически устанавливает фокус курсора в это поле при загрузке страницы.

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

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

Joomla 3 Isis

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

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

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

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

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

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

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

<field
    name="my_number"
    type="number"
    label="Количество элементов"
    description="Введите целое число от 1 до 100."
    default="10"
    min="1"
    max="100"
    step="1"/>

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

Для получения значения поля в PHP-коде используйте объект ввода (input). Применение фильтров int или float гарантирует, что данные будут приведены к числовому типу и очищены от посторонних символов, что делает их безопасными для дальнейших вычислений.

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

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

// getInt() автоматически приводит значение к целому числу (integer)
// Если нужно дробное число, используйте getFloat('my_number_field', 0.0)
$myNumber = $input->getInt('my_number_field', 0);


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

// Второй аргумент 'int' обеспечивает фильтрацию и приведение к целому числу
$myNumber = $input->get('my_number_field', 0, 'int'); 

// ИЛИ старым способом (не рекомендуется, но встречается в старом коде):
$myNumber = JRequest::getVar('my_number_field', 0, 'get', 'int');


// --- ВАЖНОЕ ПРИМЕЧАНИЕ ПО ТИПАМ ДАННЫХ ---
// Методы getInt() и getFloat() гарантируют, что вы получите числовой тип (int/float),
// а не строку. Это безопасно для математических операций.

// Пример использования в условии или математике:
if ($myNumber > 10) {
    $result = $myNumber * 2;
    echo "Результат: " . $result;
}

// Если вы использовали фильтр 'cmd' или 'string' (что плохо для чисел),
// обязательно приводите тип явно:
$unsafeValue = $input->get('my_number_field', '0', 'string');
$safeInt = (int) $unsafeValue;

Обратите внимание, что методы getInt() и getFloat() не просто извлекают данные, но и принудительно приводят их к соответствующему числовому типу PHP. Это гарантирует корректную работу математических операций и защищает код от ошибок типов, даже если пользователь попытается ввести недопустимые символы.

Совет: Если вам необходимо принимать дробные числа (например, цену или вес), обязательно установите атрибут step="0.01" (или другой нужный шаг). По умолчанию браузеры часто считают шаг равным 1, что может блокировать ввод десятичных дробей или округлять их до ближайшего целого при использовании стрелок. Для хранения таких значений в PHP используйте метод $input->getFloat() вместо getInt().

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

Строгая типизация на бэкенде: HTML-поле number отправляет данные как строку. Если вы используете фильтр 'string' или 'cmd' при получении значения через $input, вы получите строковый тип данных. Это приведет к ошибкам в математических операциях (например, "10" + "5" может сработать, но "10" * "2" потребует явного приведения типов). Всегда используйте фильтры 'int' или 'float' (методы getInt()/getFloat()), чтобы гарантировать числовой тип в PHP.
Ограничение ввода только стрелками: Атрибуты min и max ограничивают выбор значения стрелками интерфейса, но не запрещают пользователю вручную вписать число вне этого диапазона в текстовое поле. Браузер может показать предупреждение при отправке формы, но надежная проверка границ должна всегда дублироваться на стороне сервера (в PHP) перед сохранением данных.
Проблема дробных чисел по умолчанию: Если не указать атрибут step, браузер по умолчанию считает его равным 1. Это означает, что поле будет считаться «невалидным» при вводе дробных чисел (например, 1.5), а стрелки будут изменять значение только на целые единицы. Для поддержки десятичных дробей обязательно явно задавайте step="any" или конкретный шаг (например, step="0.01").
Зависимость от локали: В некоторых браузерах отображение разделителя дробной части (точка . или запятая ,) зависит от языковых настроек пользователя. Однако стандарт HTML5 требует, чтобы значение поля всегда передавалось на сервер с точкой в качестве разделителя. Если вы используете JavaScript для форматирования числа под локаль, убедитесь, что перед отправкой формы значение приводится обратно к стандартному формату с точкой, иначе PHP может не распознать его как корректное число.