Экстраполя в Cotonti: полное руководство по типу «Список с множественным выбором» (checklistbox)
Данное руководство является продолжением серии статей о дополнительных полях (Extrafields) в Cotonti CMF. Оно подробно, шаг за шагом, описывает процесс создания, настройки и использования поля типа checklistbox – группы флажков, позволяющей выбрать несколько значений одновременно. Материал рассчитан на начинающих администраторов и разработчиков, которые хотят расширить функционал своего сайта без глубокого знания PHP. Каждый шаг сопровождается реальными примерами и пояснениями, делающими инструкцию доступной даже для тех, кто впервые работает с Cotonti.
Содержание
- Что такое checklistbox и зачем он нужен
- Создание поля checklistbox в административной панели
- Вывод значений на сайте
- Как поле ведёт себя в форме редактирования
- Обработка ошибок и частые проблемы
- Заключение
1. Что такое checklistbox и зачем он нужен
Checklistbox – это тип дополнительного поля в Cotonti, который представляет собой группу флажков (чекбоксов). Пользователь может выбрать несколько вариантов одновременно. В отличие от select (одиночный выбор) или radio (одиночный выбор), checklistbox позволяет отметить любое количество пунктов. Выбранные значения сохраняются в базе данных в виде строки, где каждый выбранный ключ отделён запятой (например, новость,важно,срочно). При выводе эта строка разделяется по запятой и форматируется в соответствии с настройками или языковыми файлами.
Примеры использования checklistbox:
- Теги или метки (важно, срочно, в архив).
- Дополнительные услуги (доставка, сборка, расширенная гарантия).
- Категории внутри страницы (новости, акции, обзоры).
- Свойства товара (цвет: красный, синий, зелёный).
В этом руководстве мы создадим поле «Теги» для страниц (cot_pages) и пройдём полный цикл от настройки в админке до отображения на сайте.
2. Создание поля checklistbox в административной панели
Все дополнительные поля Cotonti управляются через интерфейс «Extrafields». Чтобы добавить поле для таблицы страниц, перейдите по адресу:
https://cotonti.local/ru/admin/extrafields?n=cot_pages
Подставьте вместо cotonti.local домен вашего сайта.
Вы увидите таблицу с уже существующими экстраполями (если они были добавлены ранее) и форму для создания нового поля. Начнём заполнять её для checklistbox.
2.1. Имя поля (Name)
В поле «Имя» (field_name) введите уникальный идентификатор, состоящий из латинских букв, цифр и знаков подчёркивания, без пробелов. Это имя будет использоваться в шаблонах и в программном коде. Оно должно быть понятным и отражать суть поля.
Пример: bookmarks – для поля «Теги».
Внимание: Не используйте дефисы, точки или кириллицу. Допустимы только символы [a-zA-Z0-9_].
2.2. Описание поля (Description)
В поле «Описание» (field_description) напишите текст, который будет отображаться как заголовок поля в форме редактирования страницы. Он также может использоваться в шаблонах через тег {ИМЯ_ПОЛЯ_TITLE}.
Пример: Теги.
2.3. Тип поля (Type)
Рядом с именем находится выпадающий список «Тип» (field_type). По умолчанию там выбрано input. Щёлкните по нему и выберите значение checklistbox. Как только вы это сделаете, некоторые поля формы изменят своё состояние: поле «Параметры» станет активным, а «Значения выбора» останется активным.
2.4. HTML-код поля (HTML)
Поле «HTML-код поля» (field_html) позволяет задать собственный внешний вид группы чекбоксов. Для начала оставьте его пустым – Cotonti сгенерирует стандартный HTML, который будет работать. Если вы захотите кастомизировать отображение, вы сможете вернуться к этому позже.
2.5. Значения для выбора (Variants)
Это самое важное поле для checklistbox. В поле «Значения для select, radio, checklistbox» (field_variants) вы должны перечислить все доступные варианты через запятую, без пробелов вокруг запятых. Каждый вариант – это короткий ключ (на латинице или кириллице, но латиница надёжнее), который будет сохраняться в базе данных при выборе пользователем. Порядок следования определяет порядок, в котором чекбоксы будут отображаться в форме.
Пример: важно,срочно,новость,архив
Если вы хотите, чтобы в ключах содержались пробелы, можно использовать подчёркивания: очень_важно,не_срочно. Но удобнее использовать однословные ключи.
Распространённая ошибка: добавление пробелов после запятых (важно, срочно, новость) приведёт к тому, что пробел станет частью ключа для второго и последующих вариантов. Это может вызвать путаницу при локализации или поиске. Лучше строго соблюдать формат ключ1,ключ2,ключ3.
2.6. Параметры (Params)
Для типа checklistbox поле «Параметры» (field_params) имеет особое значение. Сюда можно записать разделитель, который будет использоваться при отображении выбранных значений на сайте. По умолчанию, если оставить поле пустым, разделителем будет запятая с пробелом (, ).
Примеры разделителей:
,– запятая и пробел (значение по умолчанию, можно не указывать)./– слэш с пробелами, если нужно перечислить через слэш.;– точка с запятой.<br>– перенос строки (HTML-тег), если нужно вывести каждый элемент с новой строки.
В нашем примере оставим это поле пустым, чтобы использовался стандартный разделитель.
2.7. Значение по умолчанию (Default)
В поле «Значение по умолчанию» (field_default) можно указать ключи (из числа вариантов), которые будут выбраны автоматически при создании новой страницы. Если нужно выбрать несколько вариантов, перечислите их через запятую (без пробелов), например: новость,архив. Если поле оставить пустым, ни один чекбокс не будет отмечен по умолчанию.
Пример: новость – только «новость» будет выбрана по умолчанию.
2.8. Остальные настройки
- Парсинг (field_parse) – для checklistbox обычно не критичен. Оставьте значение «По умолчанию» (HTML).
- Обязательное (field_required) – если поставить галочку, пользователь должен будет выбрать хотя бы один флажок. Для нашего примера не обязательно.
- Включено (field_enabled) – должно быть включено (галочка стоит). Иначе поле не будет отображаться.
После заполнения всех полей нажмите кнопку «Добавить». Если всё введено корректно, страница перезагрузится и новое поле появится в списке. Поздравляем – вы создали поле типа checklistbox!
3. Вывод значений на сайте
Теперь, когда поле создано и работает в форме редактирования, его нужно вывести в шаблонах, чтобы посетители видели выбранные теги. Cotonti предоставляет несколько способов вывода: индивидуальные теги (как у обычных полей) и динамический блок EXTRAFLD. Рассмотрим оба подхода.
3.1. Индивидуальный вывод через теги шаблона
Как и для других типов полей, Cotonti автоматически создаёт переменные для шаблонизатора на основе имени поля. Для модуля Pages используется префикс PAGE_. Таким образом, для поля с именем bookmarks становятся доступны теги:
{PAGE_BOOKMARKS}– форматированное значение (строка с выбранными ключами, разделёнными согласно параметрам или запятыми).{PAGE_BOOKMARKS_TITLE}– описание поля (заголовок).{PAGE_BOOKMARKS_VALUE}– сырое значение, как оно хранится в базе (например,важно,срочно).
Эти теги можно разместить в любом месте шаблона page.tpl (или page.articles.tpl, если вы используете отдельный шаблон для статей).
Пример добавления в page.tpl:
<div class="page-bookmarks">
<strong>{PAGE_BOOKMARKS_TITLE}:</strong> {PAGE_BOOKMARKS}
</div>На выходе, если для страницы были выбраны теги «важно» и «срочно», вы увидите:
Теги: важно, срочноЕсли вы хотите отобразить каждый тег отдельно (например, в виде списка или с переносом строки), можно использовать сырое значение {PAGE_BOOKMARKS_VALUE} и манипулировать им в шаблоне с помощью дополнительных модификаторов. Например, для Cotonti доступен модификатор |explode(','), но его использование требует осторожности. В простейшем случае можно обойтись стандартным выводом.
3.2. Локализация (перевод) значений
По умолчанию в {PAGE_BOOKMARKS} будут показаны ключи (например, важно,срочно). Если вы хотите отобразить человекочитаемые названия (например, «Важное», «Срочное»), необходимо добавить соответствующие языковые строки. Cotonti ищет перевод для каждого значения по шаблону: имя_поля_ключ (без префикса page_).
Для нашего поля bookmarks и значения важно нужно создать строку:
$L['bookmarks_важно'] = 'Важное';Обратите внимание: ключ языковой переменной не содержит префикса page_. Именно так функция cot_build_extrafields_data() ищет перевод для значений select, radio и checklistbox. Если вы ошибочно напишете $L['page_bookmarks_важно'], перевод не сработает.
Добавьте следующие строки в языковой файл вашей темы или плагина (например, themes/mytheme/lang/theme.ru.lang.php):
$L['bookmarks_важно'] = 'Важное';
$L['bookmarks_срочно'] = 'Срочное';
$L['bookmarks_новость'] = 'Новость';
$L['bookmarks_архив'] = 'Архивное';После добавления этих строк и очистки кеша в шаблоне вместо важно, срочно вы увидите Важное, Срочное.
Примечание для продвинутых: вы можете использовать в ключах кириллицу, но это может вызвать сложности при использовании в URL или API. Рекомендуется использовать латиницу для ключей (например, important,urgent) и переводить их через языковые строки. Это обеспечит совместимость с разными языковыми версиями сайта.
3.3. Динамический вывод всех полей через блок EXTRAFLD
Индивидуальный вывод удобен, когда вы знаете все поля и их расположение. Но если экстраполей много или вы хотите вывести их единообразно, можно воспользоваться динамическим подходом. Для этого в Cotonti предусмотрен блок , который парсится в цикле для каждого активного экстраполя. Однако в стандартном модуле Pages такой цикл для страницы просмотра не реализован – он есть только для формы редактирования. Если вы хотите динамический вывод на странице просмотра, вам потребуется либо использовать плагин/кастомный хук, либо написать небольшой код.
Тем не менее, мы покажем, как это обычно делается в плагинах. Допустим, вы подключаетесь к хуку page.main и добавляете в объект шаблона $t вывод полей:
// Пример для page.main или аналогичного хука
if (!empty(Cot::$extrafields[Cot::$db->pages])) {
foreach (Cot::$extrafields[Cot::$db->pages] as $exfld) {
$tag = strtoupper($exfld['field_name']);
$value = $pag['page_' . $exfld['field_name']] ?? null;
$t->assign([
'EXTRAFIELD_TITLE' => cot_extrafield_title($exfld, 'page_'),
'EXTRAFIELD_VALUE' => cot_build_extrafields_data('page', $exfld, $value, $pag['page_parser'])
]);
$t->parse('MAIN.EXTRAFLD');
}
}В шаблоне page.tpl необходимо разместить блок:
<!-- BEGIN: EXTRAFLD -->
<div class="extrafield">
<strong>{EXTRAFIELD_TITLE}:</strong>
<span>{EXTRAFIELD_VALUE}</span>
</div>
<!-- END: EXTRAFLD -->Тогда все экстраполя, включая наш checklistbox, будут выведены автоматически друг за другом, каждое с заголовком и отформатированным значением.
3.4. Вывод в списке страниц
Когда страницы выводятся списком (например, при просмотре категории), Cotonti использует префикс LIST_ROW_. Таким образом, для поля bookmarks будут доступны теги:
{LIST_ROW_BOOKMARKS}{LIST_ROW_BOOKMARKS_TITLE}{LIST_ROW_BOOKMARKS_VALUE}
Их можно разместить внутри цикла <!-- BEGIN: LIST_ROW --> в шаблоне page.list.tpl:
<div class="bookmarks">
<strong>{LIST_ROW_BOOKMARKS_TITLE}:</strong> {LIST_ROW_BOOKMARKS}
</div>Результат будет аналогичен просмотру отдельной страницы.
4. Как поле ведёт себя в форме редактирования
После создания поля оно автоматически появляется в форме добавления/редактирования страницы. В файле modules/page/inc/page.edit.php (и аналогичных для других модулей) существует цикл, который для каждого активного экстраполя вызывает cot_build_extrafields() и присваивает результаты шаблонным переменным. Для checklistbox это будет выглядеть как группа флажков с подписями, соответствующими вариантам из «Значений выбора». Если вы указали переводы для ключей в языковом файле, они не будут автоматически применены к подписям в форме редактирования – там всегда отображаются сырые ключи. Чтобы локализовать подписи в форме, требуется дополнительная кастомизация через хуки, что выходит за рамки базового руководства.
Тем не менее, в форме редактирования вы можете выбирать несколько флажков, и при сохранении их значения будут объединены в строку через запятую и записаны в соответствующую колонку таблицы (page_bookmarks). Затем при чтении эта строка будет обработана функцией cot_build_extrafields_data(), которая разделит её по запятой и для каждого элемента найдёт перевод, если он есть.
5. Обработка ошибок и частые проблемы
- Поле не появляется в форме редактирования: проверьте, что флажок «Включено» для поля установлен, и очистите кеш.
- В шаблоне вместо перевода отображаются ключи: вы не добавили языковые строки или ошиблись в их имени. Убедитесь, что ключ имеет вид
$L['имя_поля_ключ'](например,$L['bookmarks_важно']), а не с префиксом таблицы. - Значения выводятся слитно, без разделителей: проверьте поле «Параметры» при настройке поля. Если оно пустое, используется запятая с пробелом. Если вы указали пустую строку, разделителя не будет.
- При сохранении страницы возникает ошибка SQL: возможно, поле не было создано в базе данных (колонка не добавилась). Проверьте структуру таблицы
cot_pagesчерез phpMyAdmin – там должна быть колонкаpage_bookmarks(с префиксомpage_). Если её нет, выполните вручную:ALTER TABLE cot_pages ADD page_bookmarks TEXT;. После этого обновите страницу Extrafields и пересохраните поле. - В админке поле не сохраняет выбранные значения: такое бывает при конфликте имён или из-за кеширования. Очистите кеш и попробуйте снова.
6. Заключение
Теперь вы умеете создавать, настраивать и выводить на сайте экстраполе типа «список с множественным выбором» (checklistbox). Вы узнали, как добавлять варианты, настраивать разделитель, локализовывать значения и использовать их в шаблонах как индивидуально, так и через динамический блок. Следуя этому руководству применительно к другим типам полей, вы сможете значительно расширить возможности вашего Cotonti-сайта, не прибегая к сложному программированию.
Успехов в развитии вашего проекта!
