TV в MODX: создание и вывод дополнительных полей

В уроке о шаблонах мы создали простую HTML-заготовку и назначили ее ресурсам. Теперь добавим собственное поле для изображения и выведем его на странице.

Такие поля называются TV — Template Variables, переменные шаблона или дополнительные поля. Иногда их также называют «телевизорами».

Практику выполняем стандартным синтаксисом MODX. Варианты Fenom приведены для сравнения, включать его ради этого урока не требуется.

Что такое TV в MODX

TV расширяет стандартный набор данных ресурса. Например, у страницы уже есть pagetitle, description и content, но нет отдельного поля для обложки. Его можно создать самостоятельно.

Для TV задаются имя, подпись, тип ввода и другие параметры. Затем поле связывают с шаблоном, чтобы оно появилось при редактировании соответствующих ресурсов.

Одно TV можно назначить нескольким шаблонам. Значения при этом заполняются отдельно у страниц, а не становятся одним общим значением для всего сайта.

Создаем дополнительное поле изображения

Для упражнения используем ресурс «Практикум» с шаблоном «Учебный». Если у вас другие имена, выберите свою учебную страницу и посмотрите назначенный ей шаблон.

1. Откройте вкладку «Элементы».
2. Найдите раздел дополнительных полей.
3. Нажмите кнопку создания TV или выберите соответствующую команду в контекстном меню.

Общая информация

Заполните:

• Имя: img.
• Заголовок или подпись: «Изображение страницы».
• Описание: «Выберите изображение для этой страницы».
• Категорию — при необходимости.

Имя используется в коде, подпись видит редактор при заполнении ресурса. Для новых TV удобно использовать латинские буквы и нижнее подчеркивание: img, page_image, button_text.

Имя должно быть уникальным. Не называйте TV так же, как стандартное поле ресурса. На сохраненных скриншотах имена могут отличаться; для примеров этого урока используем img.

Параметры ввода

Перейдите на вкладку «Параметры ввода» и выберите тип «Изображение».

Набор доступных параметров зависит от типа поля. Если есть настройка «Может быть не заполнено», для первого примера оставьте «Да». Значение «Нет» делает заполнение обязательным и может препятствовать сохранению ресурса без данных.

Значение по умолчанию пока можно оставить пустым. Если нужна общая картинка-заглушка, укажите существующее изображение, доступное через выбранный источник файлов.

Значение по умолчанию используется, когда у ресурса нет собственного значения TV. Это не обязательно отдельная сохраненная копия пути у каждой страницы: изменение общего значения может повлиять на использующие его ресурсы.

Параметры вывода

Для этого упражнения оставьте тип вывода по умолчанию. Мы хотим получить путь к изображению и самостоятельно разместить его в теге img.

Если выбрать вывод «Изображение», TV может возвращать уже готовую HTML-разметку. Тогда вставлять его внутрь src другого img не нужно.

Доступно для шаблонов

Отметьте шаблон «Учебный», назначенный «Практикуму».

Если «Первый материал» использует другой шаблон, например «Учебный — с примечанием», поле не появится у него, пока вы не назначите TV и этому шаблону.

Для учебного поля вкладку «Права доступа» оставляем без изменений.

Источники файлов

Проверьте источник для контекста сайта, обычно web. В установке уже может быть стандартный источник файловой системы — создавать новый только ради упражнения не требуется.

Выберите источник, через который доступно нужное изображение, или оставьте подходящий стандартный. Путь связан с настройками этого источника: не добавляйте к нему вручную assets, img или начальный слеш без проверки.

Отдельный источник с удобным базовым каталогом настроим по инструкции об источниках файлов. Сейчас сохраните TV.

Где заполнить значение TV

1. Перейдите на вкладку «Ресурсы» и откройте «Практикум».
2. Проверьте, что выбран шаблон «Учебный».
3. Откройте вкладку «Дополнительные поля».
4. Найдите «Изображение страницы».
5. Через кнопку выбора файла укажите учебное изображение и сохраните ресурс.

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

Не меняйте ограничения загрузки на любые расширения ради этого упражнения.

Сохранение самого TV создает поле и его настройки. Сохранение ресурса записывает выбранное для этой страницы значение.

Как разместить TV ниже содержимого

Можно включить системную настройку «Разместить TV ниже контента» — tvs_below_content. Тогда поля будут находиться ниже content на вкладке документа.

Менять расположение необязательно. На отображение также могут влиять настройки форм и установленные дополнения.

Выводим изображение на странице

В нашем примере MODX установлен в корне домена, а TV возвращает относительный путь без начального слеша, например assets/img/photo.jpg. В учебном шаблоне нет base, поэтому перед вызовом TV добавляем /: изображение будет запрашиваться от корня домена, а не относительно адреса вложенной страницы.

Откройте шаблон «Учебный» и после заголовка h1 добавьте:

<img src="/[[*img]]" alt="[[*pagetitle:htmlent]]" style="max-width: 100%; height: auto;">

Сохраните шаблон и откройте «Практикум» на сайте. Должно появиться выбранное изображение.

Если вместо картинки виден только путь, проверьте наличие HTML-тега img. Сам вызов TV возвращает значение, а не обязательно готовую картинку.

Fenom — для сравнения

<img src="/{$_modx->resource.img}" alt="{$_modx->resource.pagetitle | escape}" style="max-width: 100%; height: auto;">

Это альтернативная запись при настроенной обработке Fenom. Для текущего упражнения используйте стандартный вариант, не вставляйте оба изображения одновременно.

Проверка TV на заполнение

Если изображение необязательное, лучше не выводить тег с пустым src.

Стандартный вариант:

[[*img:notempty=`
    <figure>
        <img src="/[[*img]]" alt="[[*pagetitle:htmlent]]" style="max-width: 100%; height: auto;">
    </figure>
`]]

Вариант Fenom:

{if $_modx->resource.img}
    <figure>
        <img src="/{$_modx->resource.img}" alt="{$_modx->resource.pagetitle | escape}" style="max-width: 100%; height: auto;">
    </figure>
{/if}

Проверяется значение поля. Для проверки заполнения недостаточно только убедиться, что переменная существует.

Типы ввода TV

Тип ввода определяет, как редактор заполняет данные. Для большинства первых задач достаточно текста, изображения, списка или флажка.

Возможные значения для списков и переключателей

Простые варианты разделяются двумя вертикальными чертами:

Белый||Черный||Серый

Чтобы подпись отличалась от сохраняемого значения:

Белый==#ffffff||Черный==#000000

Редактор увидит «Белый» или «Черный», а значением станет соответствующий код цвета. Это только данные: применение цвета в CSS нужно реализовать отдельно.

Для нескольких вариантов по умолчанию у множественного выбора используется разделитель ||.

Тип ввода и тип вывода — разные настройки

Тип ввода «Изображение» дает инструмент выбора файла. Тип вывода определяет, как обработать значение при отображении: оставить путь, сформировать изображение, отформатировать дату или объединить несколько значений.

Поэтому в нашем примере вывод оставлен по умолчанию: тег img написан непосредственно в шаблоне.

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

TV в шаблоне и в чанке списка

Тег со звездочкой получает TV текущего ресурса: [[*img]]

Если сниппет выводит список других страниц, он должен получить их TV и передать значения в чанк. Имя плейсхолдера зависит от компонента и его параметров.

Например, у pdoResources с includeTVs=`img` и стандартным префиксом используется: [[+tv.img]]

При обработке такого чанка Fenom значение с точкой доступно через: {$_pls['tv.img']}

Поэтому правило «в чанке просто меняем звездочку на плюс» неполное. Нужно учитывать, какие данные передал конкретный сниппет. Подробный пример ниже требует установленного pdoTools.

Дополнительный пример: выбираем связанные страницы

@SELECT pagetitle, id FROM [[+PREFIX]]site_content WHERE parent = 30 AND published = 1 AND deleted = 0 ORDER BY menuindex ASC, id ASC

[[*related_pages]]

<article>
    <h3><a href="[[~[[+id]]]]">[[+pagetitle:htmlent]]</a></h3>
    [[+tv.img:notempty=`<img src="[[+tv.img]]" alt="[[+pagetitle:htmlent]]" style="max-width: 100%; height: auto;">`]]
</article>

[[[[*related_pages:notempty=`pdoResources`:default=`-`]]?
    &parents=`0`
    &resources=`[[*related_pages]]`
    &limit=`0`
    &includeTVs=`img`
    &prepareTVs=`img`
    &tpl=`tvRelatedItem`
]]

{set $selectedPages = $_modx->resource.related_pages | replace : '||' : ','}

{if $selectedPages}
    {$_modx->runSnippet('pdoResources', [
        'parents' => 0,
        'resources' => $selectedPages,
        'limit' => 0,
        'includeTVs' => 'img',
        'prepareTVs' => 'img',
        'tpl' => 'tvRelatedItem'
    ])}
{/if}

Где хранятся TV

В базе данных определения дополнительных полей, их связи с шаблонами и значения ресурсов хранятся отдельно:

• modx_site_tmplvars — определения TV.
• modx_site_tmplvar_templates — связь с шаблонами.
• modx_site_tmplvar_contentvalues — значения ресурсов.

modx_ — пример префикса. Для обычного редактирования эти таблицы открывать не требуется.

Не создавайте отдельное TV для каждого экземпляра повторяемой карточки. Если нужен список однотипных записей, стоит рассмотреть подходящую структуру данных, например MIGX. Но само количество TV не является готовым измерением скорости сайта.

Если поле не появилось или изображение не выводится

Если поле исчезло после смены шаблона, сначала проверьте назначение TV новому шаблону. Не создавайте одноименное поле заново.

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

Следующий урок

Дальше разберем чанки MODX: вынесем повторяемую разметку в отдельный элемент и научимся передавать ему данные.

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

← Предыдущая статьяШаблоны MODX: создание, назначение и редактирование

Следующая статья →Чанки MODX: создание, вызов и передача параметров