Плагин “Custom Extrafields” - Памятка про установку демо экстраполей

Статья-памятка: установочный файл демо-полей xtradbrowpage.install.php

Этот файл вызывается только один раз — при первичной установке плагина xtradbrowpage. Он создаёт в системной таблице cot_extra_fields набор демонстрационных экстраполей, чтобы сразу увидеть, как работают все поддерживаемые типы. Потом их можно отредактировать или удалить через админку «Экстраполя → cot_xtradbrowpage».

Ниже разобраны ключевые моменты, которые важно помнить, чтобы не повторять прошлых ошибок.

1. Общий шаблон вызова cot_extrafield_add()

Каждое поле добавляется функцией с 13 аргументами. В файле для каждого поля они пронумерованы и прокомментированы:

cot_extrafield_add(
   $db_xtradbrowpage,    // 1. Таблица-владелец (обязательно переменная, не строка)
   'field_name',         // 2. Имя поля в БД (без префикса таблицы)
   'тип',                // 3. Тип extrafield: input, textarea, select, radio, checkbox, datetime, double, inputint, country, range, file, checklistbox
   'html шаблон',        // 4. HTML-код поля, содержит плейсхолдеры: {$name}, {$value}, {$checked}, {$attrs}, {$options} и спец. {$day} {$month} {$year} {$hour} {$minute}
   'варианты',           // 5. Строка вариантов через запятую (для select/radio/checklistbox). Для file — расширения, для range/country — пусто
   'по_умолчанию',       // 6. Значение по умолчанию
   false,                // 7. Обязательность (false/0 — нет, true/1 — да)
   'HTML',               // 8. Парсер для вывода (обычно 'HTML', для файлов — '')
   'Описание в админке', // 9. Описание поля
   'доп.параметры',      // 10. Для datetime — "год_мин,год_макс,формат даты"; для range — "мин,макс"; для file — путь к папке
   1,                    // 11. Включено (1 — да)
   false,                // 12. Пропустить ALTER TABLE (false — создать столбец в таблице, true — только регистрация)
   'кастомный SQL-тип'   // 13. Если нужно переопределить тип столбца (например, 'INT UNSIGNED NOT NULL DEFAULT 0')
);

2. Особенности конкретных типов

input, textarea, double

Никаких сюрпризов. Просто HTML-шаблон с {$name} и {$value}.

select

Шаблон: <select ... name="{$name}">{$options}</select>.
Варианты передаются через аргумент 5 (строка через запятую). API автоматически подставит <option> из этих вариантов.

radio

Важно! Использовать плейсхолдеры {$value} (значение) и {$title} (подпись), а не {$variant}.
Шаблон:

html

<div class="form-check">
 <input class="form-check-input" type="radio" name="{$name}" value="{$value}" {$checked} />
 <label class="form-check-label">{$title}</label>
</div>

Варианты: 'Yes,No'. По умолчанию: 'No'.

checkbox

Шаблон содержит {$checked} и фиксированную подпись. Значение по умолчанию: '0' (выключен). Возвращает 1/0.

datetime

Шаблон раскладывает дату на пять селектов: {$day} {$month} {$year} {$hour} {$minute}.
В параметре 10 указываем: '2024,2030,d.m.Y H:i' (мин.год, макс.год, формат отображения).
Значение по умолчанию — timestamp (целое число). Например, '1714060800' (26.04.2024 00:00).
При сохранении дата конвертируется в timestamp и хранится как INT.

range (ползунок)

Это не HTML-ползунок! Cotonti реализует range как выпадающий список <select> с числами от мин до макс (аргумент 10: '0,100'). Поэтому шаблон должен быть как у select:

html

<select class="form-select" name="{$name}">{$options}</select>

Варианты не нужны, параметры обязательны.

checklistbox (список чекбоксов)

Шаблон содержит один чекбокс, API сам сгенерирует по одному на каждый вариант:

html

<div class="form-check">
 <input class="form-check-input" type="checkbox" name="{$name}" value="{$value}" {$checked} />
 <label class="form-check-label">{$title}</label>
</div>

Варианты: 'Опция 1,Опция 2,Опция 3'. Значение по умолчанию — строка выбранных через запятую: 'Опция 1' или 'Опция 1,Опция 3'.
При сохранении в БД попадает строка с выбранными значениями.

country

Шаблон: <select ...>{$options}</select>.
Варианты заполняются автоматически. Значение по умолчанию — двухбуквенный код страны в нижнем регистре ('ae', 'ua'). Хранится как CHAR(2).

file (загрузка файла)

Шаблон:

html

<div class="list-group">
 <div class="list-group-item list-group-item-secondary">
 <strong>Текущий файл:</strong> <span class="text-primary">{$value}</span>
 </div>
 <div class="list-group-item">
 <label>Заменить файл</label>
 <input type="file" class="form-control" name="{$name}" {$attrs}>
 </div>
 <div class="list-group-item list-group-item-danger">
 <div class="form-check">
 <input class="form-check-input" type="checkbox" name="{$delname}" value="1" id="delete_{$name}">
 <label for="delete_{$name}">Удалить текущий файл</label>
 </div>
 </div>
</div>

Расширения передаются в аргументе 5: 'jpg,png,pdf,zip'.
Путь к папке — в аргументе 10: 'datas/exflds/xtradbrowpage'.
При установке плагина папку создаём сами (см. ниже).

Критически важно: чтобы файл физически переместился из временной папки в целевую, после сохранения данных нужно вызвать cot_extrafield_movefiles(); (см. раздел 4).

3. Создание папки для файлов

В конце установочного файла обязательно добавлено:

php

if (!is_dir('datas/exflds/xtradbrowpage')) {
 mkdir('datas/exflds/xtradbrowpage', 0777, true);
 file_put_contents('datas/exflds/xtradbrowpage/.htaccess', "Order deny,allow\nDeny from all");
}

Это гарантирует, что загруженные файлы не будут доступны по прямой ссылке.

4. Обработка загрузки файлов в хуке сохранения страницы

В файле xtradbrowpage.page.edit.update.done.php после вызова xtradbrowpage_save() обязательно вызываем:

php

cot_extrafield_movefiles();

Именно эта функция фактически перемещает загруженный файл из временного каталога PHP в нашу папку datas/exflds/xtradbrowpage/, удаляет старый файл при замене, обрабатывает галку «Удалить файл». Без неё в БД запишется имя файла, но сам файл останется во временной папке и при следующем запросе исчезнет.

5. Чего нельзя делать

• Нельзя использовать типы, которых нет в ядре Cotonti (email, url, color и т.п.) — они вызовут ошибку Undefined variable $sqltype и SQLSTATE[42000].
• Для radio обязательно использовать {$value} и {$title}, а не {$variant}.
• Для range не пытаться вставить <input type="range">, только <select>.
• Не дублировать вручную чекбоксы в шаблоне checklistbox — API сделает это сам.
• Не забывать cot_extrafield_movefiles(), иначе файлы не сохранятся.

6. Резюме

Перед установкой плагина на чистую систему файл xtradbrowpage.install.php создаст все демо-поля. При возникновении ошибок во время теста проще всего удалить записи из cot_extra_fields для location = 'cot_xtradbrowpage' и переустановить плагин заново. После установки можно редактировать параметры полей прямо из админки, не трогая код.

Если что-то забылось — смотреть на пронумерованные комментарии в этом же файле: они покрывают все аргументы.