ave-cms/help/fields/templates.md

Публичный вывод и шаблоны полей

← К разделу «Поля документов»

Два режима

• doc — поле на странице документа;
• req — поле внутри запроса, списка или карточки.

По умолчанию doc вызывает renderView(), а req — renderFilter(). Для галерей и связей поведение request-режима может быть строже, чтобы тяжёлый HTML не появлялся в каждой карточке без явного шаблона.

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

Runtime выбирает первый подходящий вариант:

1. непустой шаблон конкретного поля из БД;
2. точечный PHP-шаблон типа/поля;
3. стандартный метод типа renderView() или renderFilter().

Это позволяет менять один сайт или одно поле без копирования всего класса типа.

Точечные PHP-шаблоны

Шаблоны располагаются в:

system/App/Content/Fields/Templates/<type>/

Для документного режима используются имена:

field-doc-<field-id>-<template-id>.php
field-doc-<field-alias>-<template-id>.php
field-doc-<field-id>.php
field-doc-<field-alias>.php
field-doc.php

Для режима запроса замените doc на req. Более конкретный файл имеет приоритет. template-id — необязательный ID шаблона документа/запроса, переданный runtime.

В подключённом файле доступны:

$template; // PublicFieldTemplateContext
$value;    // исходное значение
$items;    // нормализованный список элементов
$field;    // определение rubric_fields

Пример для изображения:

<?php if (!$template->isEmpty()): ?>
  <?php $image = $template->first(); ?>
  <picture class="article-cover">
    <source srcset="<?= $template->escape($template->webp($image['url'])) ?>"
            type="image/webp">
    <img src="<?= $template->escape($image['url']) ?>"
         alt="<?= $template->escape($image['description']) ?>">
  </picture>
<?php endif; ?>

Методы контекста:

Метод	Результат
type(), mode()	Тип и doc/req.
value()	Исходное значение.
field(), fieldId(), alias()	Метаданные поля.
templateId()	ID текущего шаблона.
items(), first(), isEmpty()	Нормализованные данные.
escape($value)	HTML-экранирование.
thumbnail($url, $size)	URL превью заданного размера.
webp($url)	Путь WebP-производной.
host()	Базовый адрес сайта.

Режимы и размеры thumbnail(), жизненный цикл кеша и управление производными файлами описаны в разделе Медиа и миниатюры.

Не выполняйте SQL в шаблоне. Если выводу нужны дополнительные данные, подготовьте их в типе поля, сервисе модуля или hook до рендеринга.

Шаблон из БД

Шаблоны rubric_field_template и rubric_field_template_request поддерживают:

• [tag:value] — всё значение;
• [tag:parametr:0], [tag:parametr:1] — части legacy-значения;
• [tag:label], [tag:alias], [tag:default] — свойства поля;
• [tag:if_empty]...[/tag:if_empty] и if_notempty с [tag:else];
• теги создания превью и [tag:img:...].

Для нового структурного типа предпочтительнее метод класса или PHP-шаблон с PublicFieldTemplateContext: он работает с именованными JSON-данными и не зависит от позиций через |.