Экстраполя в Cotonti: полное руководство по типу «Выпадающий список» (select)
Данное руководство подробно объясняет, как создать, настроить и использовать дополнительное поле типа «выпадающий список» (select) для модуля «Страницы» (Pages) в Cotonti CMF. Статья предназначена для начинающих администраторов и разработчиков, которые хотят расширить функциональность своего сайта без написания сложного кода. Все инструкции снабжены реальными примерами, точными названиями полей и воспроизводимыми шагами. Если вы впервые столкнулись с Cotonti — просто следуйте инструкциям, и у вас всё получится.
Что такое экстраполе типа select и зачем оно нужно
Select — это поле, которое позволяет пользователю выбрать одно значение из нескольких заранее заданных. Оно отображается в виде раскрывающегося списка (выпадающего меню). В Cotonti такое поле можно добавить к любой сущности: страницам, пользователям, категориям и т.д. После создания поле автоматически появляется в форме редактирования соответствующей сущности, а выбранное значение сохраняется в базе данных.
Примеры использования select:
- Статус материала (черновик, на проверке, опубликовано).
- Тип страницы (новость, статья, обзор).
- Уровень доступа (открытый, только для друзей, приватный).
- Категория товара (если не используется стандартная структура категорий).
Далее мы создадим такое поле для таблицы страниц (cot_pages) и рассмотрим все этапы: от настройки в админке до вывода значения на сайте.
Шаг 1: Создание поля в административной панели
Все дополнительные поля в Cotonti управляются через раздел «Extrafields» в административной панели. Чтобы добавить поле для страниц, выполните следующие действия:
- Войдите в админку вашего сайта (обычно
https://ваш-сайт.com/admin). - Перейдите в раздел «Администрирование» → «Extrafields». Вы увидите список таблиц, доступных для добавления дополнительных полей.
- Найдите строку с названием
cot_pages (или «Страницы») и нажмите на неё. Откроется страница управления экстраполями для страниц.
Теперь вы находитесь на странице, где перечислены все существующие дополнительные поля (если они есть), а ниже — форма для добавления нового. Давайте заполним её.
1.1. Имя поля (Name)
В поле «Имя» (field_name) введите уникальный идентификатор латинскими буквами и цифрами, без пробелов и специальных символов. Это имя будет использоваться в шаблонах и при программном доступе к полю. Оно не должно повторяться в рамках одной таблицы. Рекомендуется использовать осмысленные имена, например: status, content_type, priority.
Пример: status — для поля «Статус материала».
Важно: не используйте дефисы или точки, только латиницу и подчёркивания.
1.2. Описание поля (Description)
В поле «Описание» (field_description) напишите текст, который будет отображаться как заголовок поля в форме редактирования страницы и в шаблонах (если используется переменная {ИМЯ_ПОЛЯ_TITLE}). Это может быть короткая подпись на любом языке.
Пример: Статус материала.
1.3. Тип поля (Type)
Рядом с именем находится выпадающий список «Тип» (field_type). По умолчанию там выбрано input. Нажмите на него и выберите из списка значение select. Это ключевой шаг, так как он определяет, что поле будет выпадающим списком. После выбора select некоторые другие поля формы (например, «Параметры») станут неактивными — это нормально.
1.4. HTML-код поля (HTML)
Поле «HTML-код поля» (field_html) позволяет задать собственный вид поля ввода. Для типа select оставьте его пустым. Cotonti автоматически сгенерирует правильный HTML-код выпадающего списка. Если вы впишете что-то своё, это может нарушить работу.
1.5. Значения для выбора (Variants)
Это самое важное поле для типа select. В поле «Значения для select, radio, checklistbox» (field_variants) вы должны перечислить все доступные варианты через запятую, без пробелов вокруг запятых. Каждый вариант — это короткий ключ (обычно латиницей), который будет сохраняться в базе данных. Порядок следования определяет порядок пунктов в списке.
Пример: draft,pending,published — три статуса: черновик, на проверке, опубликовано.
Если вы хотите, чтобы в вариантах содержались пробелы (например, «на проверке»), то используйте подчёркивания или пишите слитно, а для отображения на сайте можно настроить локализацию (переводы) через языковые файлы. Пока же сосредоточьтесь на ключах.
Частая ошибка: добавление пробелов после запятых (draft, pending, published) приведёт к тому, что второй и третий варианты будут начинаться с пробела. Это не критично, но лучше избегать.
1.6. Значение по умолчанию (Default)
В поле «Значение по умолчанию» (field_default) можно указать один из вариантов, который будет выбран автоматически при создании новой страницы. Оно должно точно совпадать с одним из ключей, перечисленных в «Значениях выбора». Если оставить поле пустым — при создании новой страницы выпадающий список останется без выбранного элемента.
Пример: draft (тогда каждая новая страница по умолчанию будет иметь статус черновика).
1.7. Остальные настройки
- Парсинг (field_parse) — для выпадающего списка не имеет большого значения. Оставьте значение «По умолчанию» (HTML).
- Обязательное (field_required) — если поставить галочку, пользователь не сможет сохранить страницу, не выбрав значение из списка. Для нашего примера можно не включать.
- Включено (field_enabled) — галочка должна стоять (по умолчанию), иначе поле не будет активно.
- Параметры (field_params) — для типа
select это поле не используется и заблокировано. Ничего не вводите.
После того как все поля заполнены, нажмите кнопку «Добавить» (зелёная кнопка в той же строке). Если всё прошло успешно, страница перезагрузится, и новое поле появится в таблице существующих экстраполей. Поздравляем — вы создали поле типа select!
Шаг 2: Как вывести значение в шаблоне страницы (индивидуальный подход)
Теперь, когда поле существует и вы можете выбрать статус в форме редактирования страницы, необходимо отобразить его на сайте. Cotonti предоставляет два основных способа: индивидуальный (вы сами размещаете теги в нужном месте шаблона) и динамический (все экстраполя выводятся автоматически через специальный блок). Рассмотрим первый способ.
Индивидуальный вывод основан на том, что Cotonti автоматически добавляет для каждого экстраполя теги в общий массив перед рендерингом шаблона. За это отвечает функция cot_generate_pagetags() (или аналогичная для других модулей). Когда вы создали поле с именем status, Cotonti внутри себя выполняет примерно такой код (упрощённо):
// Цикл по всем зарегистрированным полям таблицы cot_pages
foreach (Cot::$extrafields[Cot::$db->pages] as $exfld) {
$tag = 'PAGE_' . strtoupper($exfld['field_name']); // PAGE_STATUS
$temp_array[$tag] = ... значение поля ...
$temp_array[$tag . '_TITLE'] = cot_extrafield_title($exfld, 'page_'); // Статус материала
}
Это значит, что в любом шаблоне, который использует префикс PAGE_ (например, page.tpl для отдельной страницы или page.list.tpl для списка), вы можете получить доступ к значению и заголовку поля.
2.1. Отображение на странице просмотра (page.tpl)
Откройте файл шаблона, отвечающий за показ полной страницы (обычно themes/ваша_тема/page.tpl или page.articles.tpl). В том месте, где вы хотите видеть статус, добавьте следующий HTML-код:
<div class="page-status">
<strong>{PAGE_STATUS_TITLE}:</strong> {PAGE_STATUS}
</div>
После сохранения шаблона и очистки кеша (Администрирование → Кэш → Очистить кэш) откройте любую страницу, у которой заполнен статус, и вы увидите что-то вроде:
Статус материала: published
Если вы хотите отобразить сырое значение (ключ, а не перевод), используйте тег {PAGE_STATUS_VALUE}. Это бывает полезно для присвоения CSS-классов или логических условий в шаблоне.
2.2. Отображение в списке страниц (page.list.tpl)
Когда страницы выводятся списком (категория, поиск), Cotonti использует другой префикс тегов: LIST_ROW_. Поэтому теги будут выглядеть так:
<!-- Внутри цикла LIST_ROW -->
<div class="page-status">
<strong>{LIST_ROW_STATUS_TITLE}:</strong> {LIST_ROW_STATUS}
</div>
Аналогично доступен тег {LIST_ROW_STATUS_VALUE} для сырого значения.
2.3. Как перевести значения на человеческий язык
По умолчанию в шаблоне вы увидите ключи (draft, pending, published), а не их расшифровку. Чтобы вместо draft показывалось «Черновик», а вместо published — «Опубликовано», необходимо создать языковые строки. Cotonti автоматически ищет перевод для значения по шаблону имя_поля_ключ без всяких префиксов. Например, для поля status и значения draft будет искаться строка $L['status_draft'].
Добавьте в языковой файл вашего плагина или темы (например, themes/ваша_тема/lang/theme.ru.lang.php) следующие строки:
$L['status_draft'] = 'Черновик';
$L['status_pending'] = 'На проверке';
$L['status_published'] = 'Опубликовано';
После этого в шаблонах вы увидите «Черновик», «На проверке» и «Опубликовано» вместо ключей.
Важно: имя поля должно быть без префикса page_! Именно status_draft, а не page_status_draft. Если вы ошибётесь, перевод не сработает.
Шаг 3: Динамический вывод всех полей через блок EXTRAFLD
Индивидуальный подход хорош, когда вы точно знаете, какие поля хотите разместить и где. Но бывает удобно вывести все экстраполя одной группой, особенно если их много или вы часто добавляете новые. Для этого Cotonti использует механизм блоков EXTRAFLD.
В файле page.edit.php (форма редактирования страницы) уже есть цикл, который для каждого экстраполя присваивает шаблонному блоку EXTRAFLD переменные {PAGEEDIT_FORM_EXTRAFLD} и {PAGEEDIT_FORM_EXTRAFLD_TITLE} и парсит этот блок. То же самое можно сделать и для страницы просмотра, но стандартный модуль pages не выводит экстраполя на просмотре через EXTRAFLD, а только генерирует индивидуальные теги (описано выше). Однако многие сторонние плагины и темы используют похожий подход.
Тем не менее, в вашем распоряжении всегда есть возможность вручную добавить в шаблон page.tpl блок . Но чтобы он заработал, необходимо в PHP-коде (например, через хуки) реализовать его обработку. Для стандартных страниц проще использовать индивидуальные теги, так как они уже работают «из коробки».
Однако если вы разрабатываете свой плагин, вы можете воспользоваться следующим подходом:
// В вашем PHP-коде (например, в хуке page.main)
if (!empty(Cot::$extrafields[Cot::$db->pages])) {
foreach (Cot::$extrafields[Cot::$db->pages] as $exfld) {
$tag = strtoupper($exfld['field_name']);
$value = $page_data['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 -->
Этот метод особенно удобен, если вы создаёте универсальные темы или плагины, которые должны автоматически подхватывать любые добавленные поля.
Шаг 4: Как поле ведёт себя в форме редактирования
Когда вы создали поле типа select, оно автоматически появляется в форме редактирования страницы. За это отвечает код в файле modules/page/inc/page.edit.php (похожий код используется и в других модулях). Принцип работы:
- Определяется массив зарегистрированных экстраполей:
Cot::$extrafields[Cot::$db->pages]. - Для каждого поля вызывается функция
cot_build_extrafields('rpage' . $exfld['field_name'], $exfld, ...), которая генерирует HTML-элемент формы. - Полученный HTML присваивается переменным шаблона
{PAGEEDIT_FORM_ИМЯ_ПОЛЯ} и {PAGEEDIT_FORM_ИМЯ_ПОЛЯ_TITLE}. - Если в шаблоне
page.edit.tpl присутствует блок , то для каждого поля он будет выведен с общими переменными {PAGEEDIT_FORM_EXTRAFLD} и {PAGEEDIT_FORM_EXTRAFLD_TITLE}.
Таким образом, в форме редактирования страницы вы увидите выпадающий список с заданными вариантами. Выбрав нужное значение и сохранив страницу, вы сохраните его в базу данных.
Шаг 5: Обработка ошибок и частые проблемы
- Поле не появляется в форме редактирования: проверьте, что флажок «Включено» для этого поля установлен (в админке Extrafields) и что вы очистили кеш.
- В шаблоне вместо значения выводится только ключ (например,
draft): вы не добавили языковые строки для перевода. См. подраздел 2.3. - При сохранении страницы выдаётся ошибка: возможно, вы неверно заполнили параметры поля (например, для других типов, но для select это маловероятно). Убедитесь, что в «Значениях выбора» нет лишних символов, и вы не пытались вписать что-то в «Параметры».
- Выпадающий список показывает пустые значения: проверьте, что в «Значениях выбора» вы не оставили пустым и что ключи написаны без пробелов.
- Перевод не подхватывается: убедитесь, что вы правильно назвали ключ языка:
$L['имя_поля_ключ'] (без префикса таблицы). И что языковой файл загружен (плагин или тема должны быть активны).
Заключение
Вы научились создавать, настраивать и использовать экстраполе типа «выпадающий список» в Cotonti. Теперь вы можете добавлять любые выборы (статусы, категории, типы) к страницам, пользователям или другим сущностям. Помните, что принципы, описанные здесь, применимы и к другим типам полей, только с поправкой на их особенности (например, для textarea не нужны варианты, а для datetime нужны параметры).
Если у вас остались вопросы, обратитесь к официальной документации Cotonti или к сообществу. Удачи в развитии вашего сайта!
