# Точечные Twig-компоненты

← [К разделу «Как собирается сайт»](README.md)

AVE.cms не использует Twig вместо шаблонов сайта, рубрик, запросов, блоков и
навигации. Эти сущности остаются основным способом сборки публичной страницы.
Twig применяется внутри сложного модуля, когда его вывод нельзя разумно собрать
обычными тегами.

## Что выбрать

| Задача | Штатный инструмент |
| --- | --- |
| Общая шапка, подвал и HTML-оболочка | Шаблон сайта |
| Страница новости, статьи или другого документа | Шаблон рубрики |
| Список документов и карточка списка | Шаблоны запроса |
| Повторяемая редактируемая вставка | Блок |
| Дерево ссылок | Навигация |
| Значение документа | Поле и его публичный шаблон |
| Каталог, корзина, поиск, авторизация или интерактивная форма | Модульный тег |

Сначала используйте подходящий инструмент из таблицы. Новый Twig-компонент нужен
только тогда, когда компоненту необходимы подготовленные сервисом данные,
состояние пользователя, API или сложное интерактивное поведение.

## Как вставляется компонент

Twig-файл не указывается непосредственно в редакторе. Модуль регистрирует
обычный публичный тег:

```text
[mod_search]
[mod_basket:mini]
[mod_gallery:12]
```

Такой тег можно поставить в шаблон сайта, рубрики, запроса или блока. Дальше
движок выполняет обычный конвейер:

```text
тег
  -> зарегистрированный обработчик модуля
  -> получение и проверка данных
  -> Twig-шаблон модуля
  -> готовый HTML
```

Редактор страницы видит стабильный тег, а не путь к PHP или Twig-файлу.
Удаление либо отключение модуля не оставляет произвольного исполняемого шаблона.

## Почему нет тега с путём к файлу

Конструкции вида `[tag:twig:путь/к/file.twig]` в AVE.cms не используются. Такой
тег позволил бы шаблону из БД самостоятельно выбирать файлы, обходить контракт
модуля и передавать в представление неподготовленные данные.

Допустимые Twig-шаблоны определяет сам модуль. Он же отвечает за:

- набор доступных данных;
- проверку параметров тега;
- права и состояние пользователя;
- подключение CSS и JavaScript;
- кеширование;
- безопасное поведение при отсутствии данных.

## Где редактировать внешний вид

Управляемые настройки и шаблоны модуля редактируются в его разделе Adminx. Если
модулю разрешено переопределение активной темой, файл размещается в:

```text
templates/<theme>/views/<module>_public/<template>.twig
```

Файловое переопределение является частью разработки темы. Оно не заменяет
штатные шаблоны рубрик и запросов и не должно использоваться только ради другой
обёртки или CSS-класса.

## Кеширование

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

Общий кеш разрешён только для детерминированного HTML, одинакового для всех
посетителей. Решение принимает разработчик модуля при регистрации тега. В
редакторе страницы этот режим не переключается.

## Практическое правило

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

## Системные блоки в Twig

Чтобы не дублировать управляемый контент внутри файлов темы, используйте:

```twig
{{ theme_sysblock('footer_contacts') }}
```

Функция принимает alias или ID системного блока и возвращает уже обработанный
HTML. Вложенные теги, параметры блока, кеширование и публичные хуки работают так
же, как при обычной вставке `[tag:sysblock:footer_contacts]` в шаблон рубрики.
Если текст должен редактироваться из панели, храните его в блоке, а в Twig
оставляйте только этот вызов.