API экстраполей (Extrafields API)

Экстраполя служат для дополнения определенными данными какие-либо сущности на сайте. Например у нас есть страницы и к ним нужно добавить новый параметр и при этом чтобы была возможность его редактирования через форму. Для этого мы заходим в админ-панель и выбираем раздел управления экстраполями для страниц, задаем идентификатор экстраполя, его название, тип элемента формы для него и другие параметры. Кроме того экстраполями можно дополнить любую таблицу в базе данных фреймворка.

Полное руководство по API Extrafields Cotonti: управление дополнительными полями без написания кода

Cotonti CMF предоставляет разработчикам и администраторам мощный встроенный инструмент — API Extrafields (система дополнительных полей). Этот API позволяет добавлять произвольные поля к любой таблице базы данных и автоматически получать для них готовые элементы форм, валидацию, сохранение и форматированный вывод. Вам не нужно писать HTML-разметку, обрабатывать POST-запросы вручную или думать о типах данных — всё это уже реализовано в ядре Cotonti.

В этой статье мы детально разберём каждую функцию API, покажем, как она работает «под капотом», и на примерах объясним, как использовать её в своих плагинах. Статья рассчитана на разработчиков, но будет полезна и продвинутым администраторам, которые хотят понимать внутреннее устройство экстраполей.

2. Архитектура экстраполей: таблицы и хуки

Таблицы

• cot_extra_fields — метаданные всех зарегистрированных полей: тип, HTML-шаблон, варианты значений, параметры, значение по умолчанию, обязательность, включённость, описание.
• Целевая таблица (например, cot_pages) — физически содержит столбцы с именами, соответствующими именам полей. При добавлении поля через API автоматически выполняется ALTER TABLE, добавляющий нужный столбец с правильным SQL-типом.

Cotonti кэширует конфигурацию полей в системном кэше, что ускоряет загрузку.

Процесс работы

1. Плагин (или ядро) регистрирует таблицу как «поддерживающую экстраполя» через cot_extrafields_register_table().
2. Администратор через панель управления создаёт поля с нужными параметрами.
3. В шаблонах (или через хуки) вызывается cot_build_extrafields(), которая генерирует HTML-код элемента ввода на основе конфигурации поля и текущего значения.
4. При отправке формы данные валидируются и очищаются функцией cot_import_extrafields(), которая возвращает значение, готовое для записи в БД.
5. Для вывода используется cot_build_extrafields_data(), которая форматирует значение (например, дату, название страны, перевод варианта).

3. Регистрация таблиц для экстраполей

Чтобы Cotonti знала, что определённая таблица может иметь дополнительные поля, используется функция:

cot_extrafields_register_table('my_table_name');

Внутри она записывает ключ в глобальный массив Cot::$extrafields. Например, плагин xtradbrowusers делает так:

Cot::$db->registerTable('xtradbrowusers');
// ... позже
function xtradbrowusers_getExtrafields() {
    return Cot::$extrafields[Cot::$db->xtradbrowusers] ?? [];
}

Это даёт возможность другим функциям (например, админке экстраполей) автоматически подхватывать эту таблицу и отображать её в списке доступных.

Важно: для таблиц, создаваемых плагинами, часто используют первичный ключ с именем id, чтобы избежать автоматического добавления префикса (user_, page_ и т.д.) при создании столбцов. Это обеспечивает прямую связь между именем поля в cot_extra_fields и именем колонки в таблице.

4. Построение полей ввода — cot_build_extrafields

Эта функция — сердце генерации форм. Она принимает имя поля (атрибут name), конфигурацию экстраполя и текущее значение, а возвращает готовый HTML-код элемента ввода.

function cot_build_extrafields($name, $extrafield, $data)

Как она работает

1. Если $data равно null, используется значение по умолчанию из конфигурации поля.
2. В зависимости от $extrafield['field_type'] выполняется соответствующий блок:
   • input, inputint, currency, double → cot_inputbox() с типом text.
   • textarea → cot_textarea().
   • select → варианты из field_variants преобразуются в массив, поддерживается перевод через $L['fieldname_variant'].
   • radio → аналогично select, но через cot_radiobox().
   • checkbox → cot_checkbox() с фиксированным значением 1.
   • datetime → разбирается field_params (мин/макс год, формат), и строится набор выпадающих списков через cot_selectbox_date().
   • country → cot_selectbox_countries().
   • range → диапазон чисел из параметров, превращается в выпадающий список.
   • checklistbox → варианты превращаются в список флажков с поддержкой множественного выбора.
   • file → cot_filebox() с указанием пути и возможностью удаления текущего файла.

Все эти функции используют стандартные шаблоны из ресурсов темы (resources.rc.php), что обеспечивает единообразный вид на всём сайте.

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

В PHP-обработчике (хуке) вы сначала получаете массив всех полей:

$extrafields = xtradbrowusers_getExtrafields();
foreach ($extrafields as $exfld) {
    $value = $existingData[$exfld['field_name']] ?? '';
    $html = cot_build_extrafields('rxtra_' . $exfld['field_name'], $exfld, $value);
    // передача в шаблон
}

В шаблоне просто выводите готовый HTML: {FIELD_HTML}. Никакой ручной работы с типами не требуется.

5. Импорт и валидация данных — cot_import_extrafields

После отправки формы необходимо получить очищенные и проверенные значения. За это отвечает функция:

function cot_import_extrafields($inputname, $extrafield, $source = 'P', $oldvalue = '', $titlePrefix = '')

Она принимает:

• $inputname — имя поля в запросе (например, rxtra_phone).
• $extrafield — конфигурация поля.
• $source — источник данных: 'P' (POST), 'G' (GET), 'C' (COOKIE) или 'D' (прямая фильтрация переданного значения).
• $oldvalue — предыдущее значение (используется для файлов, чтобы удалить старый файл при замене).
• $titlePrefix — префикс для локализованного названия поля в сообщениях об ошибках.

Валидация по типам

• input: применяется регулярное выражение из field_params, если задано; иначе очистка HTML/Text.
• inputint, range: проверка на целое число, при необходимости — вхождение в диапазон из field_params.
• currency, double: числовое значение с плавающей точкой, также с проверкой диапазона.
• textarea: импорт как HTML.
• select, radio: значение должно быть в списке разрешённых вариантов, иначе ошибка.
• checkbox: приводится к 0/1.
• datetime: сборка из нескольких полей (день, месяц, год, час, минута) в timestamp, с учётом ограничений по годам.
• country: проверка кода страны.
• checklistbox: множественный выбор, каждый элемент проверяется на допустимость, затем объединяется в строку через запятую.
• file: обработка загруженного файла: проверка расширения, формирование безопасного имени, запоминание пути для последующего перемещения. Поддерживается удаление файла (через флаг rdel_...).

Если поле обязательно (field_required = 1) и значение пустое, генерируется ошибка с локализованным сообщением.

Практический пример

В хуке сохранения профиля пользователя:

$data = [];
foreach ($extrafields as $exfld) {
    $fname = $exfld['field_name'];
    $data[$fname] = cot_import_extrafields('rxtra_' . $fname, $exfld, 'P', $oldValue, 'xtra_');
}
xtradbrowusers_save($userId, $data);
// после цикла по всем полям обязательно вызывается
cot_extrafield_movefiles();

Это гарантирует, что все введённые данные пройдут проверку и будут готовы к записи в БД.

6. Локализация заголовков — cot_extrafield_title

Каждое дополнительное поле имеет описание (field_description), которое показывается в админке и рядом с полем ввода. Но для разных языков можно задать перевод. Функция cot_extrafield_title() ищет перевод в нескольких местах в порядке приоритета:

1. $L['префикс_имяполя_title'] (если передан префикс, например 'xtra_')
2. $L['имя_таблицы_имяполя_title']
3. $L['имяполя_title']
4. Возвращает field_description, если ничего не найдено.

Таким образом, разработчику достаточно добавить в языковой файл строки вида:

$L['xtra_phone_extra_title'] = 'Телефон';

и заголовок автоматически локализуется.

7. Форматирование данных для вывода — cot_build_extrafields_data

Когда нужно показать значение экстраполя на странице (не в форме), используется эта функция. Она форматирует сырое значение из БД в читаемый вид:

• select, radio — подставляет перевод варианта.
• checkbox — возвращает 0 или 1.
• datetime — форматирует по заданному в field_params формату даты.
• checklistbox — объединяет варианты через разделитель, поддерживая перевод.
• country — просто возвращает код (название страны можно получить отдельно через языковой файл стран).
• file — возвращает имя файла.
• Остальные типы — пропускают через cot_parse с учётом настроек парсинга (HTML, Text).

Таким образом, шаблоны могут безопасно выводить {USERS_DETAILS_XTRA_PHONE} и получать уже готовое к отображению значение.

8. Стандартные HTML-конструкции — cot_default_html_construction

При создании нового поля через cot_extrafield_add() без указания HTML-шаблона используется функция cot_default_html_construction(). Она загружает ресурсные строки темы оформления (например, $R['input_text']), подставляя в них пустые атрибуты. Это даёт единообразный вид полей по умолчанию, который можно изменить глобально через тему.

Разработчику редко приходится её вызывать напрямую, но понимание этого механизма помогает кастомизировать поля, задавая собственный HTML-шаблон в админке или через cot_extrafield_add().

9. Программное управление полями: добавление, обновление, удаление

API предоставляет три функции для модификации самих экстраполей (их метаданных и соответствующих столбцов в таблицах):

• cot_extrafield_add($location, $name, $type, ...) — создаёт новое поле. Выполняет ALTER TABLE для добавления колонки с правильным SQL-типом и регистрирует метаданные в cot_extra_fields. Поддерживает параметры: HTML-шаблон, варианты, значение по умолчанию, обязательность, парсер, описание, дополнительные параметры, включённость.
• cot_extrafield_update($location, $oldname, $name, $type, ...) — изменяет существующее поле. При изменении имени или типа пересоздаёт столбец с помощью ALTER TABLE ... CHANGE. Остальные параметры обновляются в метаданных.
• cot_extrafield_remove($location, $name) — удаляет поле: удаляет запись из cot_extra_fields и дропает столбец из таблицы.

Эти функции используются в административном интерфейсе «Экстраполя», но могут вызываться и из ваших плагинов при установке/обновлении. Например, плагин xtradbrowusers при установке создаёт 15 демо-полей через cot_extrafield_add(), не требуя ручных действий.

10. Работа с файлами: загрузка, перемещение, удаление

Для полей типа file API обеспечивает полный цикл:

• cot_import_extrafields (для типа file) формирует массив $uploadfiles с информацией о загружаемом файле, проверяет расширение, генерирует уникальное безопасное имя, отмечает старый файл для удаления.
• cot_extrafield_movefiles() — после успешного сохранения данных вызывает эту функцию, которая физически перемещает загруженные файлы из временной папки в целевую директорию (указанную в field_params) и удаляет старые файлы.
• cot_extrafield_unlinkfiles($fielddata, $extrafield) — удаляет файл, связанный с экстраполем. Обычно вызывается при удалении записи-владельца (например, пользователя или товара).
• cot_import_filesarray($file_post) — вспомогательная функция для работы с множественной загрузкой файлов.

Разработчику достаточно вызвать cot_import_extrafields() для поля файла в цикле сохранения, а затем cot_extrafield_movefiles() после завершения цикла. Вся сложная логика уже реализована.

11. Хуки для расширения логики

Cotonti предоставляет хуки в ключевых точках API:

• extrafields.build.file — внутри cot_build_extrafields для типа file, позволяет изменить поведение построения файлового инпута.
• extrafields.import.file.first и extrafields.import.file.done — в cot_import_extrafields для типа file, дают возможность повлиять на обработку загружаемого файла.
• extrafields.movefiles — внутри cot_extrafield_movefiles, позволяет выполнить дополнительные действия с файлами.
• extrafields.unlinkfiles — при удалении файла.

Эти хуки позволяют плагинам расширять стандартное поведение без правки ядра.

12. Практические примеры из реальных плагинов

12.1. Добавление полей к пользователям (xtradbrowusers)

Плагин xtradbrowusers использует все описанные функции:

• При установке вызывает cot_extrafield_add() 15 раз, создавая демо-поля.
• В хуке users.edit.tags получает данные текущего пользователя через xtradbrowusers_load() и в цикле генерирует HTML для админской формы редактирования с помощью cot_build_extrafields().
• При сохранении (хук users.edit.update.done) собирает новые значения через cot_import_extrafields(), сохраняет их в свою таблицу и вызывает cot_extrafield_movefiles().
• Для публичного профиля использует cot_build_extrafields_data() для форматирования значений и cot_extrafield_title() для заголовков.

Всё это работает без написания десятков строк валидации и шаблонов — только вызовы готовых функций.

12.2. Массовое редактирование пользователей в админке плагина

В новой админке xtradbrowusers для массового редактирования используется тот же подход: в цикле по пользователям для каждого поля вызывается cot_build_extrafields(), а затем при сохранении — cot_import_extrafields(). Это обеспечивает единообразие с одиночным редактированием.

13. Заключение

API Extrafields Cotonti — это мощный слой абстракции, который берёт на себя рутинную работу с дополнительными полями. Разработчику больше не нужно беспокоиться о типах данных, безопасности, верстке и совместимости — всё уже реализовано в ядре. Использование этих функций в своих плагинах позволяет сосредоточиться на бизнес-логике, а не на инфраструктуре.

Если вы пишете плагин, которому нужны настраиваемые поля — не изобретайте велосипед, используйте предоставленный API. А если вы администратор, то теперь вы знаете, что «под капотом» работают надёжные и гибкие механизмы, готовые к любым вашим задачам.