TVGroup

TVGroup — это TV-параметр, который объединяет несколько нативных полей MODX (а также MIGX) в одном интерфейсе и хранит все их значения в одном значении TV в формате JSON. Поля описываются прямо в «Параметрах ввода» TV с родными настройками каждого типа (min/max у числа, regex у текста и т.д.). Поддерживается условная логика: отображение одних полей в зависимости от значений или заполненности других.

{"type": "image", "logo": "assets/images/logo.png", "price": "500"}

Требования: MODX 3.0+, PHP 8.0+.

Использование

Создайте TV-параметр и во вкладке Параметры ввода в поле Тип ввода выберите «Группа полей». Ниже появится таблица полей группы. Каждое поле настраивается в отдельном окне со следующими свойствами:

Название

Латиница в нижнем регистре, цифры и _, начинается с буквы. По этому названию значение доступно в шаблонах.

Примечание

У каждого поля есть неизменяемый ключ: на него ссылаются условия, а при переименовании поля значения в ресурсах (и в записях MIGX-TV) переносятся на новое название при сохранении TV.

Подпись и Описание

Текст, который видит менеджер над полем.

Тип

Любой нативный тип ввода MODX: текст, textarea, richtext, число, дата, список, чекбокс, image, file и т.д. Для типа доступны его родные параметры ввода (min/max у числа, regex у текста, источник файлов у image).

Возможные значения и Значение по умолчанию

Работают так же, как у обычных TV: Картинка==image||Ссылка==link.

Обязательное

Проверяется только когда поле видно (не скрыто условиями).

Поле «Из TV» Необязательный

Живая ссылка на существующую TV (как inputTV в MIGX): тип, возможные значения, параметры, значение по умолчанию и источник файлов берутся из неё. Изменения в такой TV сразу действуют во всех группах, где она используется.

Сохранять значение, когда поле скрыто

Значение не стирается, пока условия скрывают поле: можно переключать варианты (например, тип баннера), не вводя данные заново. В выводе [[*имя_TV]] скрытое поле по-прежнему не появляется.

Условная логика

Для каждого поля можно задать правила «Показывать, если»: группы «или» из правил «и». Условия ставятся по полям выше текущего.

Доступные операторы: ==, !=, >, <, >=, <=, «пустое», «не пустое», «содержит», «регулярное выражение».

Подсказка

Скрытые условиями поля не сохраняются, если у поля не включено «Сохранять значение, когда поле скрыто».

Данные и вывод

Значение TV в ресурсе — JSON по названиям полей. Вывод [[*имя_TV]] (и getTVValue, и {$_modx->resource.имя_TV} в pdoTools) отдаёт тот же JSON без полей, скрытых условиями:

{set $promo = $_modx->resource.promo | fromJSON}
{if $promo.type == 'image'}<img src="{$promo.logo}">{/if}

Поля «из TV» типов image и file в выводе получают путь медиа-источника TV: значение banner.webp из источника с корнем assets/images/ отдаётся как /assets/images/banner.webp.

Примечание

Сырое значение из БД (например, includeTVs без processTVs) содержит и сохранённые значения скрытых полей.

Сниппет getTvGroup

Выводит поля группы в чанк. Без &tpl возвращает тот же JSON, что и [[*имя_TV]].

Название	По умолчанию	Описание
id	Текущий ресурс	ID ресурса
tv		Имя TV или её id; с &value необязателен
value		Сырое значение группы (JSON) — читается вместо значения TV из ресурса, &id не нужен
tpl		Чанк, @INLINE или @FILE; пусто — JSON
prefix	tv	Плейсхолдеры вида [[+tv.поле]]; пустая строка — [[+поле]]

[[getTvGroup? &id=`5` &tv=`promo` &tpl=`promo.tpl`]]
[[getTvGroup? &tv=`promo` &tpl=`@INLINE <b>[[+tv.type]]</b>: [[+tv.price]] ₽`]]
[[getTvGroup? &tv=`promo` &prefix=`` &tpl=`promo.tpl`]]

Множественные значения хранятся строкой a||b, их можно разбить модификатором: [[+tv.tags:split=`||`]].

Важно

Сниппет читает TV другого ресурса, поэтому вызывайте его некэшируемым: [[!getTvGroup? ...]] — иначе правка ресурса не сбросит кеш страницы. По той же причине @INLINE с плейсхолдерами надёжно работает только при вызове без кеша.

Режим &value

С &value сниппету достаточно сырого JSON группы и шаблона: ресурс и TV не загружаются. Если при этом передать и &tv, значение дополнительно проходит фильтр скрытых условиями полей и получает пути медиа-источников — как при чтении из ресурса.

Работа с MIGX

Всё, что связано с MIGX, включается, только если MIGX установлен. Интеграция работает в обе стороны.

Группа внутри MIGX

Группа подключается к MIGX как обычное поле — inputTV:

[{"caption": "Слайд", "fields": [
    {"field": "slide", "caption": "Слайд", "inputTV": "promo"}
]}]

Значение группы хранится вложенной строкой JSON внутри MIGX-массива. На фронте её можно декодировать повторно ({$row.slide | fromJSON}) или вывести сниппетом getTvGroup прямо в чанке getImageList:

[[!getImageList? &tvname=`slides` &tpl=`slideRow`]]

[[- чанк slideRow: ]]
[[!getTvGroup? &value=`[[+slide]]` &tv=`promo` &tpl=`promo.tpl`]]

MIGX внутри группы

MIGX добавляется в группу как обычное поле «из TV»: создайте MIGX-TV и сошлитесь на неё. Условная логика и сбор значений работают и внутри окна MIGX, включая вложенные конструкции «MIGX в группе в MIGX».

Рендерер превью this.renderTvGroup

Рендерер выводит превью записи группы прямо в таблице MIGX:

[{"header": "Слайд", "dataIndex": "slide", "renderer": "this.renderTvGroup"}]

Как выглядит превью, задаётся в настройках группы, поле «Шаблон превью (MIGX)», в синтаксисе Ext.XTemplate:

<b>{type}</b>: {price} ₽<tpl if="logo"> <img src="{logo:this.thumb}"></tpl>

• значения приходят в шаблон текстом: без HTML-тегов и экранированными — разметка берётся только из самого шаблона;
• {logo:this.thumb} — URL миниатюры (phpThumb) с источником файлов поля;
• форматы Ext.util.Format: {note:ellipsis(40)} и т.д.;
• поля, скрытые условиями, в шаблоне пустые;
• без шаблона выводится «Название: значение» заполненных полей.

Подсказка

Рендерер только отображает данные и ничего не дописывает в запись MIGX (в отличие от this.renderChunk, который подменяет значение колонки).

Импорт и экспорт полей

Конфигурацию группы можно выгрузить в JSON и перенести на другой сайт или в другую группу — файлом или вставкой. Поля «из TV» выгружаются как свои текстовые поля: после импорта привяжите их к нужным TV переключателем «Из TV».

Ограничения

• Типы tag и autotag внутри группы не поддерживаются: нативный рендер собирает теги из значений TV по её id, а поле группы — виртуальная TV в памяти с синтетическим id, поэтому список тегов пуст.
• Группу нельзя вложить в группу.
• MIGXDB (собственные таблицы MIGX, CMP) не поддерживается: группу туда подключить можно, но условия отображения и сборка значения там не работают, а миграция значений при переименовании полей до migxdb-таблиц не доходит.
• Клиентские правила «Настроек форм» (перемещение, скрытие) для полей «из TV» внутри группы не действуют; серверное правило значения по умолчанию (tvDefault) применяется, как у обычных TV.

Системные настройки

tvgroup.core_path

Переопределяет путь к core/components/tvgroup — удобно при разработке с символическими ссылками на репозиторий.

tvgroup.assets_path

Переопределяет путь к assets/components/tvgroup.

tvgroup.assets_url

Переопределяет URL к assets/components/tvgroup.